umgr 0.1.4

data/lib/umgr/import_result_builder.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Umgr
+  module ImportResultBuilder
+    module_function
+
+    def call(state_backend:, options:, provider_registry:)
+      desired_state = options.fetch(:desired_state)
+      imported_resources = import_resources(
+        desired_state.fetch(:resources, []),
+        provider_registry
+      )
+      final_state = build_final_state(desired_state.fetch(:version), imported_resources)
+      state_backend.write(final_state)
+      build_result(options, state_backend, final_state)
+    end
+
+    def import_resources(resources, provider_registry)
+      resources.flat_map do |resource|
+        import_resource(resource, provider_registry)
+      end
+    end
+
+    def import_resource(resource, provider_registry)
+      provider_name = resource.fetch(:provider)
+      provider = provider_registry.fetch(provider_name)
+      current_result = provider.current(resource: resource)
+      ensure_successful_current!(current_result, provider_name)
+      extract_resources(current_result, resource)
+    end
+
+    def ensure_successful_current!(result, provider_name)
+      return unless result.fetch(:ok, result.fetch('ok', true)) == false
+
+      message = result[:error] || result['error'] || "provider current failed for #{provider_name}"
+      raise Errors::InternalError, message
+    end
+
+    def extract_resources(result, fallback_resource)
+      imported_accounts = result[:imported_accounts] || result['imported_accounts']
+      return imported_accounts if imported_accounts.is_a?(Array)
+
+      resource = result[:resource] || result['resource']
+      return [resource] if resource
+
+      account = result[:account] || result['account']
+      return [fallback_resource.merge(attributes: account)] if account.is_a?(Hash)
+
+      raise Errors::InternalError, 'Provider current result missing imported resources'
+    end
+
+    def build_final_state(version, imported_resources)
+      enriched = DesiredStateEnricher.call(version: version, resources: imported_resources)
+      deduped_resources = deduplicate_by_identity(enriched.fetch(:resources))
+      {
+        version: version,
+        resources: deduped_resources
+      }
+    end
+
+    def deduplicate_by_identity(resources)
+      unique = {}
+      resources.each { |resource| unique[resource.fetch(:identity)] = resource }
+      unique.values.sort_by { |resource| resource.fetch(:identity) }
+    end
+
+    def build_result(options, state_backend, final_state)
+      {
+        ok: true,
+        action: 'import',
+        status: 'imported',
+        options: options,
+        state_path: state_backend.path,
+        state: final_state,
+        imported_count: final_state.fetch(:resources).length
+      }
+    end
+  end
+end

data/lib/umgr/plan_result_builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Umgr
+  module PlanResultBuilder
+    module_function
+
+    def call(state_backend:, options:, provider_registry: nil)
+      desired_state = options.fetch(:desired_state)
+      current_state = DesiredStateEnricher.call(state_backend.read || StateTemplate::INITIAL_STATE)
+      changeset = build_changeset(
+        desired_state: desired_state,
+        current_state: current_state,
+        provider_registry: provider_registry
+      )
+      build_result(options: options, state_backend: state_backend, current_state: current_state, changeset: changeset)
+    end
+
+    def build_changeset(desired_state:, current_state:, provider_registry:)
+      changeset = ChangeSetBuilder.call(
+        desired_resources: desired_state.fetch(:resources, []),
+        current_resources: current_state.fetch(:resources, [])
+      )
+      return changeset unless provider_registry
+
+      changeset.merge(changes: enrich_changes(changeset.fetch(:changes), provider_registry))
+    end
+
+    def enrich_changes(changes, provider_registry)
+      changes.map { |change| enrich_change(change, provider_registry) }
+    end
+
+    def enrich_change(change, provider_registry)
+      provider_name = provider_name_for(change)
+      return change unless provider_name
+
+      provider = provider_registry.fetch(provider_name)
+      provider_result = provider.plan(desired: change[:desired], current: change[:current])
+      return change unless include_provider_plan?(provider_result)
+
+      change.merge(provider_plan: compact_provider_plan(provider_result))
+    end
+
+    def provider_name_for(change)
+      resource = change[:desired] || change[:current]
+      return nil unless resource
+
+      resource[:provider] || resource['provider']
+    end
+
+    def include_provider_plan?(provider_result)
+      return false unless provider_result.is_a?(Hash)
+
+      provider_result.fetch(:ok, provider_result.fetch('ok', nil)) != false
+    end
+
+    def compact_provider_plan(provider_result)
+      compacted = provider_result.dup
+      %i[desired current].each { |key| compacted.delete(key) }
+      %w[desired current].each { |key| compacted.delete(key) }
+      compacted
+    end
+
+    def build_result(options:, state_backend:, current_state:, changeset:)
+      result = { ok: true, action: 'plan', status: 'planned', options: options, state_path: state_backend.path }
+      result.merge(
+        current_state: current_state,
+        changeset: changeset,
+        drift: DriftReportBuilder.call(changeset.fetch(:summary))
+      )
+    end
+  end
+end

data/lib/umgr/provider.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Umgr
+  class Provider
+    def validate(resource:)
+      _ = resource
+      raise Errors::AbstractMethodError, "#{self.class} must implement #validate(resource:)"
+    end
+
+    def current(resource:)
+      _ = resource
+      raise Errors::AbstractMethodError, "#{self.class} must implement #current(resource:)"
+    end
+
+    def plan(desired:, current:)
+      _ = desired
+      _ = current
+      raise Errors::AbstractMethodError, "#{self.class} must implement #plan(desired:, current:)"
+    end
+
+    def apply(changeset:)
+      _ = changeset
+      raise Errors::AbstractMethodError, "#{self.class} must implement #apply(changeset:)"
+    end
+  end
+end

data/lib/umgr/provider_contract.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Umgr
+  module ProviderContract
+    METHODS = %i[validate current plan apply].freeze
+
+    module_function
+
+    def validate!(provider)
+      invalid_methods = METHODS.reject do |method_name|
+        provider.respond_to?(method_name) && provider.method(method_name).owner != Provider
+      end
+      return provider if invalid_methods.empty?
+
+      raise Errors::ProviderContractError,
+            "Provider #{provider.class} must implement concrete methods: #{invalid_methods.join(', ')}"
+    end
+  end
+end

data/lib/umgr/provider_registry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Umgr
+  class ProviderRegistry
+    def initialize
+      @providers = {}
+      register(:echo, Providers::EchoProvider.new)
+      register(:github, Providers::GithubProvider.new)
+    end
+
+    def register(name, provider)
+      normalized_name = normalize_name(name)
+      ProviderContract.validate!(provider)
+      providers[normalized_name] = provider
+    end
+
+    def fetch(name)
+      providers[normalize_name(name)]
+    end
+
+    def names
+      providers.keys.sort
+    end
+
+    private
+
+    attr_reader :providers
+
+    def normalize_name(name)
+      normalized = name.to_s.strip
+      raise Errors::ValidationError, 'Provider name must be a non-empty string or symbol' if normalized.empty?
+
+      normalized.to_sym
+    end
+  end
+end

data/lib/umgr/provider_resource_validator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Umgr
+  module ProviderResourceValidator
+    module_function
+
+    def validate!(desired_state:, provider_registry:)
+      desired_state.fetch(:resources, []).each do |resource|
+        provider = provider_registry.fetch(resource[:provider])
+        result = provider.validate(resource: resource)
+        raise_validation_error!(provider: provider, resource: resource, result: result) if invalid_result?(result)
+      end
+    end
+
+    def invalid_result?(result)
+      return false unless result.is_a?(Hash)
+
+      result[:ok] == false || result['ok'] == false
+    end
+
+    def raise_validation_error!(provider:, resource:, result:)
+      message = result[:error] || result['error'] || "Provider #{provider.class} validation returned `ok: false`"
+      identity = resource[:identity] || ResourceIdentity.call(resource)
+      raise Errors::ValidationError, "#{message} for resource #{identity}"
+    end
+  end
+end

data/lib/umgr/providers/echo_provider.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Umgr
+  module Providers
+    class EchoProvider < Provider
+      def validate(resource:)
+        {
+          ok: true,
+          provider: 'echo',
+          resource: resource
+        }
+      end
+
+      def current(resource:)
+        {
+          ok: true,
+          provider: 'echo',
+          account: resource.fetch(:attributes, {}),
+          resource: resource
+        }
+      end
+
+      def plan(desired:, current:)
+        status = desired == current ? 'no_change' : 'update'
+        {
+          ok: true,
+          provider: 'echo',
+          status: status,
+          desired: desired,
+          current: current
+        }
+      end
+
+      def apply(changeset:)
+        {
+          ok: true,
+          provider: 'echo',
+          status: 'applied',
+          changeset: changeset
+        }
+      end
+    end
+  end
+end

data/lib/umgr/providers/github/account_normalizer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Umgr
+  module Providers
+    module GithubAccountNormalizer
+      module_function
+
+      def call(user:, org:, teams:)
+        login = fetch_value(user, :login)
+        resource = base_resource(login: login)
+        resource.merge(
+          identity: ResourceIdentity.call(resource),
+          org: org,
+          teams: teams.sort,
+          attributes: normalized_attributes(user)
+        )
+      end
+
+      def normalized_attributes(user)
+        {
+          id: fetch_value(user, :id),
+          login: fetch_value(user, :login),
+          avatar_url: fetch_value(user, :avatar_url),
+          html_url: fetch_value(user, :html_url),
+          type: fetch_value(user, :type)
+        }.compact
+      end
+
+      def base_resource(login:)
+        {
+          provider: 'github',
+          type: 'user',
+          name: login
+        }
+      end
+
+      def fetch_value(payload, key)
+        value = payload[key] if payload.respond_to?(:[])
+        value ||= payload[key.to_s] if payload.respond_to?(:[])
+        value ||= payload.public_send(key) if payload.respond_to?(key)
+        value
+      end
+    end
+  end
+end

data/lib/umgr/providers/github/api_client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'octokit'
+
+module Umgr
+  module Providers
+    class GithubApiClient
+      def list_org_users(org:, token:)
+        with_api_error_handling do
+          build_client(token: token).org_members(org)
+        end
+      end
+
+      def list_org_team_memberships(org:, token:)
+        with_api_error_handling do
+          client = build_client(token: token)
+          teams = client.org_teams(org)
+          build_team_memberships(client: client, teams: teams)
+        end
+      end
+
+      def invite_org_member(org:, login:, token:)
+        with_api_error_handling do
+          build_client(token: token).update_organization_membership(org, user: login, role: 'member')
+        end
+      end
+
+      def remove_org_member(org:, login:, token:)
+        with_api_error_handling do
+          build_client(token: token).remove_organization_membership(org, user: login)
+        end
+      end
+
+      def add_team_membership(org:, team_slug:, login:, token:)
+        with_api_error_handling do
+          client = build_client(token: token)
+          team_id = team_id_for!(client: client, org: org, team_slug: team_slug)
+          client.add_team_membership(team_id, login)
+        end
+      end
+
+      def remove_team_membership(org:, team_slug:, login:, token:)
+        with_api_error_handling do
+          client = build_client(token: token)
+          team_id = team_id_for!(client: client, org: org, team_slug: team_slug)
+          client.remove_team_membership(team_id, login)
+        end
+      end
+
+      private
+
+      def build_client(token:)
+        Octokit::Client.new(access_token: token, auto_paginate: true)
+      end
+
+      def build_team_memberships(client:, teams:)
+        memberships = Hash.new { |memo, key| memo[key] = [] }
+
+        teams.each do |team|
+          team_id = fetch_value(team, :id)
+          team_slug = fetch_value(team, :slug)
+          next unless team_id && team_slug
+
+          add_team_members!(memberships: memberships, client: client, team_id: team_id, team_slug: team_slug)
+        end
+
+        memberships.transform_values!(&:sort)
+      end
+
+      def add_team_members!(memberships:, client:, team_id:, team_slug:)
+        members = client.team_members(team_id)
+
+        members.each do |member|
+          login = fetch_value(member, :login)
+          next unless login
+
+          memberships[login] << team_slug
+        end
+      end
+
+      def fetch_value(payload, key)
+        return normalize_value(payload.public_send(key)) if payload.respond_to?(key)
+        return fetch_indexed_value(payload, key) if payload.respond_to?(:[])
+
+        nil
+      end
+
+      def fetch_indexed_value(payload, key)
+        normalize_value(payload[key] || payload[key.to_s])
+      end
+
+      def normalize_value(value)
+        value.is_a?(String) ? value : value&.to_s
+      end
+
+      def team_id_for!(client:, org:, team_slug:)
+        teams = client.org_teams(org)
+        matched = teams.find { |team| fetch_value(team, :slug) == team_slug }
+        return fetch_value(matched, :id) if matched
+
+        raise Errors::ValidationError, "GitHub team not found in org #{org}: #{team_slug}"
+      end
+
+      def with_api_error_handling
+        yield
+      rescue Octokit::Error => e
+        raise Errors::ApiError, "GitHub API request failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/umgr/providers/github/apply_executor.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Umgr
+  module Providers
+    module GithubApplyExecutor
+      module_function
+
+      def call(changeset:, api_client:, token_resolver:, present_string:, plan_resolver:)
+        resource = changeset[:desired] || changeset[:current] || {}
+        org = resource[:org] || resource['org']
+        raise Errors::ValidationError, 'GitHub apply requires non-empty `org`' unless present_string.call(org)
+
+        token = token_resolver.call(resource)
+        operations = resolve_operations(changeset, plan_resolver)
+        executed_operations = execute_operations(api_client, org, token, operations)
+        apply_result(operations, executed_operations)
+      end
+
+      def resolve_operations(changeset, plan_resolver)
+        provider_plan = changeset[:provider_plan] || changeset['provider_plan'] || {}
+        operations = provider_plan[:operations] || provider_plan['operations']
+        return operations if operations.is_a?(Array)
+
+        plan_resolver.call(changeset[:desired], changeset[:current]).fetch(:operations)
+      end
+
+      def execute_operations(api_client, org, token, operations)
+        operations.map do |operation|
+          execute_operation(api_client, org, token, operation)
+          operation
+        end
+      end
+
+      def execute_operation(api_client, org, token, operation)
+        dispatch_operation(api_client, org, token, normalize_operation(operation))
+      end
+
+      def dispatch_operation(api_client, org, token, operation)
+        handler = operation_handlers(api_client, org, token)[operation[:type]]
+        return handler.call(operation) if handler
+
+        raise Errors::InternalError, "Unsupported GitHub apply operation: #{operation[:type]}"
+      end
+
+      def operation_handlers(api_client, org, token)
+        {
+          'invite_org_member' => ->(operation) { invite_operation(api_client, org, token, operation) },
+          'remove_org_member' => ->(operation) { remove_org_operation(api_client, org, token, operation) },
+          'add_team_membership' => ->(operation) { add_team_operation(api_client, org, token, operation) },
+          'remove_team_membership' => ->(operation) { remove_team_operation(api_client, org, token, operation) },
+          'no_change' => ->(_operation) {}
+        }
+      end
+
+      def invite_operation(api_client, org, token, operation)
+        api_client.invite_org_member(org: org, login: operation[:login], token: token)
+      end
+
+      def remove_org_operation(api_client, org, token, operation)
+        api_client.remove_org_member(org: org, login: operation[:login], token: token)
+      end
+
+      def add_team_operation(api_client, org, token, operation)
+        api_client.add_team_membership(org: org, team_slug: operation[:team], login: operation[:login], token: token)
+      end
+
+      def remove_team_operation(api_client, org, token, operation)
+        api_client.remove_team_membership(org: org, team_slug: operation[:team], login: operation[:login], token: token)
+      end
+
+      def normalize_operation(operation)
+        {
+          type: operation[:type] || operation['type'],
+          login: operation[:login] || operation['login'],
+          team: operation[:team] || operation['team']
+        }
+      end
+
+      def apply_result(operations, executed_operations)
+        {
+          ok: true,
+          provider: 'github',
+          status: 'applied',
+          operations: operations,
+          executed_operations: executed_operations
+        }
+      end
+    end
+  end
+end

data/lib/umgr/providers/github/plan_builder.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Umgr
+  module Providers
+    module GithubPlanBuilder
+      module_function
+
+      def call(desired:, current:)
+        team_actions = build_team_actions(desired: desired, current: current)
+        login = extract_login(desired, current)
+        organization_action = organization_action_for(desired: desired, current: current)
+        operations = build_plan_operations(
+          organization_action: organization_action,
+          login: login,
+          team_add: team_actions[:add],
+          team_remove: team_actions[:remove]
+        )
+
+        plan_result(organization_action: organization_action, operations: operations, team_actions: team_actions)
+      end
+
+      def extract_teams(resource)
+        return [] unless resource.is_a?(Hash)
+
+        raw = resource[:teams] || resource['teams'] || []
+        Array(raw).map(&:to_s).reject(&:empty?).uniq.sort
+      end
+
+      def extract_login(desired, current)
+        resource = desired || current
+        return nil unless resource.is_a?(Hash)
+
+        login = resource[:name] || resource['name']
+        login&.to_s
+      end
+
+      def organization_action_for(desired:, current:)
+        return 'invite' if desired && !current
+        return 'remove' if current && !desired
+
+        'keep'
+      end
+
+      def build_team_actions(desired:, current:)
+        desired_teams = extract_teams(desired)
+        current_teams = extract_teams(current)
+        {
+          add: desired_teams - current_teams,
+          remove: current_teams - desired_teams,
+          unchanged: desired_teams & current_teams
+        }
+      end
+
+      def plan_result(organization_action:, operations:, team_actions:)
+        {
+          ok: true,
+          provider: 'github',
+          status: 'planned',
+          organization_action: organization_action,
+          team_actions: team_actions,
+          operations: operations
+        }
+      end
+
+      def build_plan_operations(organization_action:, login:, team_add:, team_remove:)
+        case organization_action
+        when 'invite'
+          build_invite_operations(login: login, team_add: team_add)
+        when 'remove'
+          [{ type: 'remove_org_member', login: login }]
+        else
+          build_membership_operations(login: login, team_add: team_add, team_remove: team_remove)
+        end
+      end
+
+      def build_invite_operations(login:, team_add:)
+        operations = [{ type: 'invite_org_member', login: login }]
+        operations.concat(team_add.map { |team| { type: 'add_team_membership', login: login, team: team } })
+        operations
+      end
+
+      def build_membership_operations(login:, team_add:, team_remove:)
+        operations = []
+        operations.concat(team_add.map { |team| { type: 'add_team_membership', login: login, team: team } })
+        operations.concat(team_remove.map { |team| { type: 'remove_team_membership', login: login, team: team } })
+        operations = [{ type: 'no_change', login: login }] if operations.empty?
+        operations
+      end
+    end
+  end
+end