organizations 0.5.0 → 0.7.0

data/lib/generators/organizations/join/templates/app/views/organization_joins/show.html.erb

@@ -0,0 +1,113 @@
+<%# The join screen: one URL, four states, all decided by
+    Organizations::JoinState, so the page and its forms always agree.
+    Generated by `rails g organizations:join`. Retheme it freely; keep the
+    disclosure visible before every submit (see OrganizationJoinsController). %>
+
+<div class="mx-auto max-w-lg">
+  <div class="mb-8 text-center">
+    <span class="mx-auto mb-4 inline-flex h-14 w-14 items-center justify-center rounded-2xl bg-slate-600 text-2xl font-bold text-white">
+      <%= @organization.name.first.upcase %>
+    </span>
+    <h1 class="text-2xl font-bold text-gray-900"><%= @organization.name %></h1>
+    <p class="mt-1 text-sm text-gray-500"><%= @organization.member_count %> members</p>
+  </div>
+
+  <div class="rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
+    <% case @state.status %>
+    <% when :member %>
+
+      <div class="text-center">
+        <%= heroicon "check-circle", variant: :outline, options: { class: "mx-auto h-12 w-12 text-green-500" } %>
+        <h2 class="mt-2 text-lg font-semibold text-gray-900">You're a member!</h2>
+        <p class="mt-1 text-sm text-gray-500">You already belong to <%= @organization.name %>.</p>
+        <%= link_to "Go to dashboard", root_path,
+              class: "mt-4 inline-flex items-center rounded-lg bg-slate-600 px-4 py-2 text-sm font-semibold text-white hover:bg-slate-700" %>
+      </div>
+
+    <% when :verifying %>
+
+      <h2 class="text-lg font-semibold text-gray-900">Check your inbox</h2>
+      <p class="mt-1 text-sm text-gray-500">
+        We sent a 6-digit code to <span class="font-medium text-gray-900"><%= @state.challenge.verification_email %></span>.
+      </p>
+
+      <%= form_with url: organization_join_path(@organization), method: :post, class: "mt-4 space-y-3" do |form| %>
+        <%= form.text_field :verification_code,
+              autofocus: true, autocomplete: "one-time-code", inputmode: "numeric", maxlength: 6,
+              placeholder: "123456",
+              class: "block w-full rounded-lg border-gray-300 text-center text-2xl tracking-[0.5em] focus:border-slate-500 focus:ring-slate-500" %>
+        <%= form.submit "Verify", class: "w-full rounded-lg bg-slate-600 px-4 py-2 text-sm font-semibold text-white hover:bg-slate-700 cursor-pointer" %>
+      <% end %>
+
+      <%# resend_seconds derives from gem config — never mirror the throttle
+          as a magic number in your app. %>
+      <div class="mt-4 border-t border-gray-100 pt-4 text-center text-sm text-gray-500">
+        <% if @state.resend_seconds.zero? %>
+          <%= form_with url: organization_join_path(@organization), method: :post, class: "inline" do |form| %>
+            <%= form.hidden_field :email, value: @state.challenge.verification_email %>
+            <%= form.submit "Resend code", class: "font-medium text-slate-600 hover:text-slate-800 cursor-pointer bg-transparent border-0 p-0" %>
+          <% end %>
+        <% else %>
+          You can request another code in <%= @state.resend_seconds %>s.
+        <% end %>
+      </div>
+
+    <% when :pending %>
+
+      <div class="text-center">
+        <%= heroicon "clock", variant: :outline, options: { class: "mx-auto h-12 w-12 text-amber-500" } %>
+        <h2 class="mt-2 text-lg font-semibold text-gray-900">Request pending</h2>
+        <p class="mt-1 text-sm text-gray-500">An admin of <%= @organization.name %> will review your request.</p>
+        <%= button_to "Withdraw request", organization_withdraw_join_path(@organization), method: :delete,
+              class: "mt-4 text-sm font-medium text-gray-500 hover:text-red-600 cursor-pointer bg-transparent" %>
+      </div>
+
+    <% when :entry %>
+
+      <h2 class="text-lg font-semibold text-gray-900">Join <%= @organization.name %></h2>
+
+      <%= render "organization_joins/disclosure", organization: @organization %>
+
+      <%# The capability predicates decide which forms exist — an org with no
+          domains never shows an email form, etc. %>
+      <% if @organization.accepts_domain_joining? %>
+        <%= form_with url: organization_join_path(@organization), method: :post, class: "mt-4 space-y-3" do |form| %>
+          <label class="block text-sm font-medium text-gray-700">Your work email</label>
+          <%= form.email_field :email, placeholder: "you@company.com", required: true, maxlength: 254,
+                class: "block w-full rounded-lg border-gray-300 focus:border-slate-500 focus:ring-slate-500" %>
+          <%= form.submit "Send verification code", class: "w-full rounded-lg bg-slate-600 px-4 py-2 text-sm font-semibold text-white hover:bg-slate-700 cursor-pointer" %>
+        <% end %>
+      <% end %>
+
+      <% if @organization.accepts_code_joining? %>
+        <div class="<%= "mt-4 border-t border-gray-100 pt-4" if @organization.accepts_domain_joining? %>">
+          <%= form_with url: organization_join_path(@organization), method: :post, class: "space-y-3" do |form| %>
+            <label class="block text-sm font-medium text-gray-700">Have a join code?</label>
+            <%= form.text_field :code, value: @staged_code, placeholder: "XXXX-XXXX", maxlength: 32,
+                  class: "block w-full rounded-lg border-gray-300 uppercase tracking-widest focus:border-slate-500 focus:ring-slate-500" %>
+            <%= form.submit "Join with code", class: "w-full rounded-lg border border-slate-600 px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50 cursor-pointer" %>
+          <% end %>
+        </div>
+      <% end %>
+
+      <%# A request with no code and no email. JoinFlow joins right away when
+          the account email is confirmed at a domain of this organization;
+          otherwise the admins decide. %>
+      <% if @organization.accepts_join_requests? %>
+        <div class="mt-4 border-t border-gray-100 pt-4">
+          <%= form_with url: organization_join_path(@organization), method: :post, class: "space-y-3" do |form| %>
+            <label class="block text-sm font-medium text-gray-700">Or ask to join</label>
+            <%= form.text_area :message, rows: 2, maxlength: 500, placeholder: "A note for the admins (optional)",
+                  class: "block w-full rounded-lg border-gray-300 text-sm focus:border-slate-500 focus:ring-slate-500" %>
+            <%= form.submit "Ask to join", class: "w-full rounded-lg border border-gray-300 px-4 py-2 text-sm font-semibold text-gray-700 hover:bg-gray-50 cursor-pointer" %>
+          <% end %>
+        </div>
+      <% end %>
+
+      <% unless @organization.accepts_join_requests? %>
+        <p class="mt-2 text-sm text-gray-500">This organization is not accepting join requests right now.</p>
+      <% end %>
+
+    <% end %>
+  </div>
+</div>

data/lib/generators/organizations/join/templates/routes.rb

@@ -0,0 +1,19 @@
+  # organizations: join and access screens (rails g organizations:join)
+  scope "orgs/:organization_id", as: :organization do
+    get    "join", to: "organization_joins#show", as: :join
+    post   "join", to: "organization_joins#create"
+    delete "join", to: "organization_joins#withdraw", as: :withdraw_join
+
+    get    "access", to: "organization_access#show", as: :access
+    post   "access/domains", to: "organization_access#add_domain", as: :access_domains
+    patch  "access/domains/:domain_id", to: "organization_access#update_domain", as: :access_domain
+    delete "access/domains/:domain_id", to: "organization_access#remove_domain"
+    post   "access/domains/:domain_id/verification", to: "organization_access#start_domain_verification", as: :access_domain_verification
+    post   "access/domains/:domain_id/verify", to: "organization_access#verify_domain", as: :verify_access_domain
+    post   "access/codes", to: "organization_access#generate_code", as: :access_codes
+    post   "access/codes/:code_id/revoke", to: "organization_access#revoke_code", as: :revoke_access_code
+    post   "access/allowlist", to: "organization_access#import_allowlist", as: :access_allowlist
+    delete "access/allowlist/:entry_id", to: "organization_access#remove_allowlist_entry", as: :access_allowlist_entry
+    post   "access/requests/:request_id/approve", to: "organization_access#approve_request", as: :approve_access_request
+    post   "access/requests/:request_id/reject", to: "organization_access#reject_request", as: :reject_access_request
+  end

data/lib/generators/organizations/upgrade/templates/add_domain_verification.rb.erb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Upgrades organizations <= 0.6.x to 0.7.0: domain authority and sign-up
+# domain policies. Additive only. Existing domains start unverified with the
+# "none" policy: nothing changes until you verify a domain or turn on
+# config.require_verified_domains.
+class AddDomainVerification < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # ⚠️ If your user model is NOT `User` (config.user_class), change
+    # `to_table: :users` to your user table before migrating.
+    change_table :organizations_domains do |t|
+      t.string :join_policy, null: false, default: "none"
+      t.string :verification_token
+      t.datetime :verification_started_at
+      t.datetime :verified_at
+      t.string :verification_method
+      t.references :verified_by, null: true, type: foreign_key_type,
+                                 foreign_key: { to_table: :users, on_delete: :nullify }
+      t.datetime :verification_revoked_at
+    end
+  end
+
+  private
+
+  def foreign_key_type
+    config = Rails.configuration.generators
+    config.options[config.orm][:primary_key_type] || :bigint
+  end
+end

data/lib/generators/organizations/upgrade/templates/add_personal_organizations.rb.erb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Upgrades organizations <= 0.6.x to 0.7.0: personal organizations.
+# Additive only. Existing organizations stay unclassified (personal_owner_id
+# is NULL): link the ones you have reviewed with
+# Organizations::Organization.backfill_personal_owners!(mapping, dry_run: true).
+class AddPersonalOrganizations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # ⚠️ If your user model is NOT `User` (config.user_class), change
+    # `to_table: :users` to your user table before migrating.
+    add_reference :organizations_organizations, :personal_owner,
+                  null: true, type: foreign_key_type, index: { unique: true },
+                  foreign_key: { to_table: :users, on_delete: :nullify }
+  end
+
+  private
+
+  def foreign_key_type
+    config = Rails.configuration.generators
+    config.options[config.orm][:primary_key_type] || :bigint
+  end
+end

data/lib/generators/organizations/upgrade/upgrade_generator.rb

@@ -5,43 +5,108 @@ require "rails/generators/active_record"
 
 module Organizations
   module Generators
-    # Upgrades an existing organizations install (<= 0.4.x) to 0.5.0
-    # ("Verified Joining"): new tables for domains, join codes, allowlist
-    # entries and join requests, plus provenance columns on memberships and
-    # metadata columns on invitations.
+    # Brings an existing organizations install up to date. Each step is one
+    # additive migration, generated only when the app does not have it yet:
     #
-    # Fresh installs don't need this — `rails g organizations:install`
-    # already includes everything.
+    #   0.5.0 - verified joining: domains, join codes, allowlist entries,
+    #           join requests, membership provenance, invitation metadata
+    #   0.7.0 - personal organizations (organizations.personal_owner_id)
+    #   0.7.0 - domain authority (verification and join policy on domains)
+    #
+    # A step counts as present when the database already has its table or
+    # column (when the generator can connect), when its upgrade migration is
+    # already in db/migrate, or when the app's install migration already
+    # creates it (an install made on a later version). Run it after every
+    # upgrade of the gem:
     #
     #   rails g organizations:upgrade
     #   rails db:migrate
     #
+    # For a squashed or renamed migration history, name the steps you need:
+    #
+    #   rails g organizations:upgrade --steps add_personal_organizations
+    #
     class UpgradeGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
-      desc "Add the verified-joining tables/columns (organizations 0.5.0) to an existing install"
+      desc "Add the tables and columns of newer organizations versions to an existing install"
+
+      # migration name => [text the install migration contains when it creates
+      # this step, [table, column] that exist once it ran (column nil = table only)]
+      STEPS = {
+        "add_verified_joining_to_organizations" => ["organizations_domains", ["organizations_domains", nil]],
+        "add_personal_organizations" => ["personal_owner", %w[organizations_organizations personal_owner_id]],
+        "add_domain_verification" => ["verification_token", %w[organizations_domains verification_token]]
+      }.freeze
+
+      class_option :steps, type: :array, default: nil,
+                           desc: "Generate exactly these steps and skip detection (#{STEPS.keys.join(', ')})"
 
       def self.next_migration_number(dir)
         ActiveRecord::Generators::Base.next_migration_number(dir)
       end
 
-      def create_migration_file
-        migration_template "add_verified_joining_to_organizations.rb.erb",
-                           File.join(db_migrate_path, "add_verified_joining_to_organizations.rb"),
-                           migration_version: migration_version
+      def create_migration_files
+        @created = []
+        selected_steps.each do |name|
+          next if options[:steps].nil? && step_present?(name)
+
+          migration_template "#{name}.rb.erb", File.join(db_migrate_path, "#{name}.rb"),
+                             migration_version: migration_version
+          @created << name
+        end
       end
 
       def display_post_upgrade_message
-        say "\n✅ organizations verified-joining migration created.", :green
+        if @created.empty?
+          say "\n✅ organizations is up to date: no migration needed.", :green
+          return
+        end
+
+        say "\n✅ organizations upgrade migrations created: #{@created.join(', ')}.", :green
         say "\nNext steps:"
         say "  1. Run 'rails db:migrate'."
-        say "  2. See the README's \"Verified joining\" section for the new API"
-        say "     (domains, join codes, allowlists, join requests)."
+        say "  2. See CHANGELOG.md for what each version adds."
       end
 
       private
 
+      def selected_steps
+        return STEPS.keys unless options[:steps]
+
+        unknown = options[:steps] - STEPS.keys
+        raise Thor::Error, "Unknown step(s): #{unknown.join(', ')}. Valid: #{STEPS.keys.join(', ')}" if unknown.any?
+
+        STEPS.keys & options[:steps]
+      end
+
+      def step_present?(name)
+        marker, (table, column) = STEPS.fetch(name)
+        in_database?(table, column) || in_migrations?(name, marker)
+      end
+
+      # false when there is no database to ask (the generator still works offline).
+      def in_database?(table, column)
+        check = ->(c) { c.table_exists?(table) && (column.nil? || c.column_exists?(table, column)) }
+        return ActiveRecord::Base.with_connection(&check) if ActiveRecord::Base.respond_to?(:with_connection)
+
+        check.call(ActiveRecord::Base.connection) # Rails 7.1
+      rescue StandardError
+        false
+      end
+
+      def in_migrations?(name, marker)
+        migration_files.any? do |file|
+          File.basename(file).match?(/\A\d+_#{name}\.rb\z/) ||
+            (File.basename(file).match?(/\A\d+_create_organizations_tables\.rb\z/) && File.read(file).include?(marker))
+        end
+      end
+
+      def migration_files
+        @migration_files ||= Dir[File.join(destination_root, db_migrate_path, "*.rb")]
+      end
+
       def migration_version
         "[#{ActiveRecord::VERSION::STRING.to_f}]"
       end

data/lib/generators/organizations/views/templates/organizations/invitations/_form.html.erb

@@ -35,7 +35,7 @@
   <div>
     <%= form.label :role, "Role", class: "block text-sm font-medium text-gray-700 mb-1" %>
     <%= form.select :role,
-      Organizations::Roles::HIERARCHY.reject { |role| role == :owner }.map { |role| [role.to_s.capitalize, role] },
+      Organizations::Roles.hierarchy.select { |role| role != :owner && current_membership&.can_assign_role?(role) }.map { |role| [organization_role_label(role, organization: current_organization), role] },
       { selected: @invitation.role || :member },
       required: true,
       class: "block w-full rounded-lg border-gray-300 shadow-sm focus:border-slate-500 focus:ring-slate-500 sm:text-sm" %>

data/lib/generators/organizations/views/templates/organizations/invitations/index.html.erb

@@ -54,7 +54,7 @@
                     when 'member' then 'bg-blue-100 text-blue-800'
                     else 'bg-gray-100 text-gray-800'
                     end %>">
-                <%= invitation.role.capitalize %>
+                <%= organization_role_label(invitation.role, organization: invitation.organization) %>
               </span>
             </td>
             <td class="px-6 py-4 whitespace-nowrap">
@@ -84,7 +84,7 @@
               <% end %>
             </td>
             <td class="px-6 py-4 whitespace-nowrap text-right">
-              <% if invitation.pending? %>
+              <% if invitation.pending? && current_membership&.can_assign_role?(invitation.role) %>
                 <div class="flex items-center justify-end gap-2">
                   <%= button_to resend_organization_invitation_path(invitation),
                     method: :post,

data/lib/generators/organizations/views/templates/organizations/invitations/show.html.erb

@@ -21,7 +21,7 @@
                 else 'bg-gray-100 text-gray-800'
                 end %>">
             <%= heroicon "user-circle", variant: :solid, options: { class: "h-5 w-5" } %>
-            You'll join as <%= @invitation.role.capitalize %>
+            You'll join as <%= organization_role_label(@invitation.role, organization: @invitation.organization) %>
           </span>
         </div>
 

data/lib/generators/organizations/views/templates/organizations/memberships/index.html.erb

@@ -48,33 +48,41 @@
                     when 'member' then 'bg-blue-100 text-blue-800'
                     else 'bg-gray-100 text-gray-800'
                     end %>">
-                <%= membership.role.capitalize %>
+                <%= organization_role_label(membership.role, organization: membership.organization) %>
               </span>
             </td>
             <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
               <%= time_ago_in_words(membership.created_at) %> ago
             </td>
             <td class="px-6 py-4 whitespace-nowrap text-right">
+              <% can_change_role = can_change_member_role?(current_user, membership) %>
+              <% can_remove = can_remove_member?(current_user, membership) %>
               <% if is_current_user %>
                 <span class="text-sm text-gray-400 italic">Current user</span>
               <% elsif membership.role == 'owner' %>
                 <span class="text-sm text-gray-400 italic">Organization owner</span>
+              <% elsif !can_change_role && !can_remove %>
+                <span class="text-sm text-gray-400 italic">No actions</span>
               <% else %>
                 <div class="flex items-center justify-end gap-2">
-                  <%= form_with(model: membership, url: membership_path(membership), method: :patch, local: true, class: "flex items-center gap-2") do |form| %>
-                    <%= form.select :role,
-                      Organizations::Roles::HIERARCHY.reject { |r| r == :owner }.map { |role| [role.to_s.capitalize, role] },
-                      { selected: membership.role },
-                      class: "rounded-md border-gray-300 text-sm focus:border-slate-500 focus:ring-slate-500" %>
-                    <%= form.submit "Update",
-                      class: "inline-flex items-center rounded-md bg-white px-2.5 py-1.5 text-xs font-semibold text-gray-700 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-50 cursor-pointer" %>
+                  <% if can_change_role %>
+                    <%= form_with(model: membership, url: membership_path(membership), method: :patch, local: true, class: "flex items-center gap-2") do |form| %>
+                      <%= form.select :role,
+                        Organizations::Roles.hierarchy.select { |r| r != :owner && current_membership.can_assign_role?(r) }.map { |role| [organization_role_label(role, organization: membership.organization), role] },
+                        { selected: membership.role },
+                        class: "rounded-md border-gray-300 text-sm focus:border-slate-500 focus:ring-slate-500" %>
+                      <%= form.submit "Update",
+                        class: "inline-flex items-center rounded-md bg-white px-2.5 py-1.5 text-xs font-semibold text-gray-700 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-50 cursor-pointer" %>
+                    <% end %>
                   <% end %>
 
-                  <%= button_to membership_path(membership),
-                    method: :delete,
-                    data: { turbo_confirm: "Remove #{membership.user.email} from the organization?" },
-                    class: "inline-flex items-center rounded-md bg-red-50 px-2 py-1.5 text-xs font-medium text-red-700 hover:bg-red-100" do %>
-                    <%= heroicon "trash", variant: :mini, options: { class: "h-4 w-4" } %>
+                  <% if can_remove %>
+                    <%= button_to membership_path(membership),
+                      method: :delete,
+                      data: { turbo_confirm: "Remove #{membership.user.email} from the organization?" },
+                      class: "inline-flex items-center rounded-md bg-red-50 px-2 py-1.5 text-xs font-medium text-red-700 hover:bg-red-100" do %>
+                      <%= heroicon "trash", variant: :mini, options: { class: "h-4 w-4" } %>
+                    <% end %>
                   <% end %>
                 </div>
               <% end %>

data/lib/generators/organizations/views/templates/organizations/organizations/index.html.erb

@@ -64,7 +64,7 @@
                     when 'member' then 'bg-blue-100 text-blue-800'
                     else 'bg-gray-100 text-gray-800'
                     end %>">
-                <%= membership&.role&.capitalize || "Unknown" %>
+                <%= membership ? organization_role_label(membership.role, organization: organization) : "Unknown" %>
               </span>
             </td>
             <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500 bg-inherit">

data/lib/generators/organizations/views/templates/organizations/organizations/show.html.erb

@@ -59,7 +59,7 @@
       </div>
       <div>
         <p class="text-sm text-gray-500">Your Role</p>
-        <p class="text-2xl font-bold text-gray-900"><%= current_user.role_in(@organization)&.capitalize || "N/A" %></p>
+        <p class="text-2xl font-bold text-gray-900"><%= (role = current_user.role_in(@organization)) ? organization_role_label(role, organization: @organization) : "N/A" %></p>
       </div>
     </div>
   </div>
@@ -117,7 +117,7 @@
                   when 'member' then 'bg-blue-100 text-blue-800'
                   else 'bg-gray-100 text-gray-700'
                   end %>">
-              <%= membership.role.capitalize %>
+              <%= organization_role_label(membership.role, organization: @organization) %>
             </span>
           </div>
 
@@ -126,7 +126,7 @@
             <div class="flex items-center gap-2">
               <%= form_with(model: membership, url: organizations.membership_path(membership), method: :patch, local: true, class: "flex items-center gap-2") do |form| %>
                 <%= form.select :role,
-                  Organizations::Roles::HIERARCHY.reject { |r| r == :owner }.map { |role| [role.to_s.capitalize, role] },
+                  Organizations::Roles.hierarchy.reject { |r| r == :owner }.map { |role| [organization_role_label(role, organization: @organization), role] },
                   { selected: membership.role },
                   class: "rounded-md border-gray-300 text-xs focus:border-slate-500 focus:ring-slate-500 py-1" %>
                 <%= form.submit "Update",

data/lib/generators/organizations/views/views_generator.rb

@@ -17,10 +17,8 @@ module Organizations
     # so the dummy remains the living, boot-able preview of what you get).
     #
     # NOTE: verified joining (join screens, request queues, access
-    # management) is deliberately NOT part of this set — those surfaces are
-    # host ROUTES + CONTROLLERS too, not just views. Copy the reference
-    # implementation from the gem's test/dummy app instead (see README
-    # "Verified joining — reference UI").
+    # management) is not part of this set: those surfaces are host routes
+    # and controllers too. `rails g organizations:join` copies them.
     class ViewsGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
@@ -38,8 +36,8 @@ module Organizations
         say "The organization page's owner-only Danger Zone (transfer/delete) renders only if you"
         say "provide app/views/shared/_danger_zone.html.erb — copy the full-featured one (Stimulus"
         say "confirm modal included) from the gem's test/dummy app."
-        say "Verified-joining surfaces (join screen, request queue, access management) are host"
-        say "controllers + views: copy the reference implementation from the gem's test/dummy app."
+        say "For the join screen and the access screen (domains, codes, allowlist, requests),"
+        say "run `rails g organizations:join`."
         say ""
       end
     end

data/lib/organizations/account_deletion_plan.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Organizations
+  # What deleting a user would do to their organizations, under a policy
+  # (config.account_deletion_policy). user.account_deletion_plan returns one
+  # without changing anything; the deletion guard builds one under row locks
+  # and acts on it.
+  #
+  #   plan = user.account_deletion_plan
+  #   plan.allowed?                  # => false
+  #   plan.blockers                  # => [#<Blocker organization=…, reason=:owns_organization_with_members>]
+  #   plan.organizations_to_destroy  # personal organizations deleted with the account
+  #   plan.memberships_to_remove     # the user's other memberships, removed with the account
+  #
+  # Blocker reasons:
+  #   :owns_organization_with_members     - transfer ownership first
+  #   :owns_organization                  - the user is the only member; delete the organization first
+  #   :personal_organization_with_members - the personal organization has other members
+  #   :personal_organization              - the policy is :prevent
+  #
+  # Database effects only. Subscriptions, external services and retained
+  # records belong to the host's account-closure workflow: a rollback cannot
+  # undo an external call, so run those after the deletion commits.
+  class AccountDeletionPlan
+    Blocker = Struct.new(:organization, :reason, keyword_init: true)
+
+    BLOCKER_REASONS = %i[
+      owns_organization_with_members
+      owns_organization
+      personal_organization_with_members
+      personal_organization
+    ].freeze
+
+    attr_reader :user, :policy, :blockers, :organizations_to_destroy, :memberships_to_remove
+
+    # @param user [User]
+    # @param policy [Symbol] one of Configuration::ACCOUNT_DELETION_POLICIES
+    # @param lock [Boolean] lock the owned organizations (the deletion guard does)
+    def self.for(user, policy: Organizations.configuration.account_deletion_policy, lock: false)
+      new(user, policy.to_sym, lock: lock)
+    end
+
+    def initialize(user, policy, lock: false)
+      unless Configuration::ACCOUNT_DELETION_POLICIES.include?(policy)
+        raise ArgumentError, "Unknown account deletion policy: #{policy.inspect}"
+      end
+
+      @user = user
+      @policy = policy
+      @blockers = []
+      @organizations_to_destroy = []
+      classify(owned_organizations(lock: lock))
+      @memberships_to_remove = remaining_memberships
+    end
+
+    # @return [Boolean] true when the user can be deleted
+    def allowed?
+      blockers.empty?
+    end
+
+    # A plain Hash (ids and symbols) for audit logs and confirmation screens.
+    # @return [Hash]
+    def to_h
+      {
+        allowed: allowed?,
+        policy: policy,
+        blockers: blockers.map { |b| { organization_id: b.organization.id, reason: b.reason } },
+        organizations_to_destroy: organizations_to_destroy.map(&:id),
+        memberships_to_remove: memberships_to_remove.map(&:id)
+      }
+    end
+
+    private
+
+    # Organizations the user owns, plus any organization still linked to them
+    # as personal owner (a raw write can leave a link without the membership).
+    def owned_organizations(lock:)
+      owned_ids = Membership.where(user_id: user.id, role: "owner").select(:organization_id)
+      scope = Organization.where(id: owned_ids)
+      scope = scope.or(Organization.where(personal_owner_id: user.id)) if personal_column?
+      scope = scope.order(:id)
+      lock ? scope.lock.to_a : scope.to_a
+    end
+
+    def classify(organizations)
+      @shared_ids = Membership.where(organization_id: organizations.map(&:id)).where.not(user_id: user.id)
+        .distinct.pluck(:organization_id).to_set
+      organizations.each do |organization|
+        reason = blocker_reason(organization)
+        if reason
+          blockers << Blocker.new(organization: organization, reason: reason)
+        else
+          organizations_to_destroy << organization
+        end
+      end
+    end
+
+    def blocker_reason(organization)
+      others = @shared_ids.include?(organization.id)
+      personal = personal_column? && organization.personal_owner_id == user.id
+
+      return (others ? :owns_organization_with_members : :owns_organization) unless personal
+      return :personal_organization_with_members if others
+      return :personal_organization unless policy == :destroy_personal_organization
+
+      nil
+    end
+
+    def remaining_memberships
+      Membership.where(user_id: user.id).where.not(organization_id: organizations_to_destroy.map(&:id))
+        .where.not(role: "owner").order(:id).to_a
+    end
+
+    def personal_column?
+      Organization.column_names.include?("personal_owner_id")
+    end
+  end
+end