umgr 0.1.4

data/spec/import_result_builder_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::ImportResultBuilder do
+  let(:state_backend) { instance_double(Umgr::StateBackend, path: '/tmp/.umgr/state.json') }
+  let(:provider_registry) { instance_double(Umgr::ProviderRegistry) }
+  let(:provider) { instance_double(Umgr::Providers::EchoProvider) }
+  let(:desired_state) do
+    {
+      version: 1,
+      resources: [
+        { provider: 'echo', type: 'user', name: 'alice', attributes: { team: 'platform' } }
+      ]
+    }
+  end
+  let(:options) { { config: '/tmp/users.yml', desired_state: desired_state } }
+
+  it 'imports provider current state and persists deduplicated resources' do
+    allow(provider_registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:current).and_return(
+      ok: true,
+      imported_accounts: [
+        { provider: 'echo', type: 'user', name: 'alice', attributes: { team: 'infra' } },
+        { provider: 'echo', type: 'user', name: 'alice', attributes: { team: 'platform' } },
+        { provider: 'echo', type: 'user', name: 'bob' }
+      ]
+    )
+    allow(state_backend).to receive(:write)
+
+    result = described_class.call(state_backend: state_backend, options: options, provider_registry: provider_registry)
+
+    expect(result[:ok]).to be(true)
+    expect(result[:status]).to eq('imported')
+    expect(result[:imported_count]).to eq(2)
+    expect(state_backend).to have_received(:write).with(
+      {
+        version: 1,
+        resources: [
+          {
+            provider: 'echo',
+            type: 'user',
+            name: 'alice',
+            attributes: { team: 'platform' },
+            identity: 'echo.user.alice'
+          },
+          {
+            provider: 'echo',
+            type: 'user',
+            name: 'bob',
+            identity: 'echo.user.bob'
+          }
+        ]
+      }
+    )
+  end
+
+  it 'uses returned resource payload when provider returns a single resource' do
+    allow(provider_registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:current).and_return(
+      ok: true,
+      resource: { provider: 'echo', type: 'user', name: 'carla', attributes: { title: 'manager' } }
+    )
+    allow(state_backend).to receive(:write)
+
+    result = described_class.call(state_backend: state_backend, options: options, provider_registry: provider_registry)
+    imported = result.fetch(:state).fetch(:resources)
+
+    expect(imported).to eq(
+      [{ provider: 'echo', type: 'user', name: 'carla', attributes: { title: 'manager' }, identity: 'echo.user.carla' }]
+    )
+  end
+
+  it 'raises internal error when provider current returns ok: false' do
+    allow(provider_registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:current).and_return(ok: false, error: 'denied')
+    allow(state_backend).to receive(:write)
+
+    expect do
+      described_class.call(state_backend: state_backend, options: options, provider_registry: provider_registry)
+    end.to raise_error(Umgr::Errors::InternalError, /denied/)
+    expect(state_backend).not_to have_received(:write)
+  end
+
+  it 'uses account fallback shape when provider returns account attributes hash' do
+    allow(provider_registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:current).and_return(
+      ok: true,
+      account: { team: 'security', title: 'engineer' }
+    )
+    allow(state_backend).to receive(:write)
+
+    result = described_class.call(state_backend: state_backend, options: options, provider_registry: provider_registry)
+    resource = result.fetch(:state).fetch(:resources).first
+
+    expect(resource).to eq(
+      provider: 'echo',
+      type: 'user',
+      name: 'alice',
+      attributes: { team: 'security', title: 'engineer' },
+      identity: 'echo.user.alice'
+    )
+  end
+
+  it 'raises internal error when provider current returns no recognized resource keys' do
+    allow(provider_registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:current).and_return(ok: true, ignored: 'value')
+    allow(state_backend).to receive(:write)
+
+    expect do
+      described_class.call(state_backend: state_backend, options: options, provider_registry: provider_registry)
+    end.to raise_error(Umgr::Errors::InternalError, /missing imported resources/)
+    expect(state_backend).not_to have_received(:write)
+  end
+
+  it 'raises internal error when account fallback is not a hash' do
+    allow(provider_registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:current).and_return(ok: true, account: 'some_string')
+    allow(state_backend).to receive(:write)
+
+    expect do
+      described_class.call(state_backend: state_backend, options: options, provider_registry: provider_registry)
+    end.to raise_error(Umgr::Errors::InternalError, /missing imported resources/)
+    expect(state_backend).not_to have_received(:write)
+  end
+end

data/spec/plan_result_builder_spec.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::PlanResultBuilder do
+  let(:state_backend) { instance_double(Umgr::StateBackend, path: '/tmp/.umgr/state.json') }
+  let(:desired_state) do
+    {
+      version: 1,
+      resources: [
+        { provider: 'echo', type: 'user', name: 'alice', identity: 'echo.user.alice' }
+      ]
+    }
+  end
+  let(:options) { { config: '/tmp/users.yml', desired_state: desired_state } }
+
+  it 'uses persisted state when available' do
+    allow(state_backend).to receive(:read).and_return(
+      version: 1,
+      resources: [{ provider: 'echo', type: 'user', name: 'alice', identity: 'echo.user.alice' }]
+    )
+
+    result = described_class.call(state_backend: state_backend, options: options)
+
+    expect(result[:status]).to eq('planned')
+    expect(result[:current_state][:resources].size).to eq(1)
+    expect(result[:changeset][:summary]).to eq(create: 0, update: 0, delete: 0, no_change: 1)
+    expect(result[:drift]).to eq(
+      detected: false,
+      change_count: 0,
+      actions: { create: 0, update: 0, delete: 0 }
+    )
+  end
+
+  it 'falls back to shared initial state when no persisted state exists' do
+    allow(state_backend).to receive(:read).and_return(nil)
+
+    result = described_class.call(state_backend: state_backend, options: options)
+
+    expect(result[:status]).to eq('planned')
+    expect(result[:current_state]).to eq(Umgr::StateTemplate::INITIAL_STATE)
+    expect(result[:changeset][:summary]).to eq(create: 1, update: 0, delete: 0, no_change: 0)
+    expect(result[:drift]).to eq(
+      detected: true,
+      change_count: 1,
+      actions: { create: 1, update: 0, delete: 0 }
+    )
+  end
+
+  it 'enriches changes with provider-specific plan details when registry is provided' do
+    provider_registry = instance_double(Umgr::ProviderRegistry)
+    provider = instance_double(Umgr::Providers::GithubProvider)
+    desired = { provider: 'github', type: 'user', name: 'alice', identity: 'github.user.alice', teams: ['admins'] }
+    current = { provider: 'github', type: 'user', name: 'alice', identity: 'github.user.alice', teams: ['platform'] }
+    allow(state_backend).to receive(:read).and_return(version: 1, resources: [current])
+    allow(provider_registry).to receive(:fetch).with('github').and_return(provider)
+    allow(provider).to receive(:plan).with(desired: desired, current: current).and_return(
+      ok: true,
+      provider: 'github',
+      status: 'planned',
+      operations: [{ type: 'add_team_membership', team: 'admins', login: 'alice' }]
+    )
+    custom_options = { config: '/tmp/users.yml', desired_state: { version: 1, resources: [desired] } }
+
+    result = described_class.call(
+      state_backend: state_backend,
+      options: custom_options,
+      provider_registry: provider_registry
+    )
+
+    change = result.fetch(:changeset).fetch(:changes).first
+    expect(change[:action]).to eq('update')
+    expect(change.fetch(:provider_plan)).to eq(
+      ok: true,
+      provider: 'github',
+      status: 'planned',
+      operations: [{ type: 'add_team_membership', team: 'admins', login: 'alice' }]
+    )
+  end
+
+  it 'keeps change unchanged when provider name cannot be resolved' do
+    provider_registry = instance_double(Umgr::ProviderRegistry)
+    change = { identity: 'unknown.user.alice', action: 'update', desired: nil, current: nil }
+
+    result = described_class.send(:enrich_change, change, provider_registry)
+
+    expect(result).to eq(change)
+  end
+
+  it 'keeps change unchanged when provider plan result is not includable' do
+    provider_registry = instance_double(Umgr::ProviderRegistry)
+    provider = instance_double(Umgr::Providers::GithubProvider)
+    desired = { provider: 'github', type: 'user', name: 'alice', identity: 'github.user.alice', teams: [] }
+    current = { provider: 'github', type: 'user', name: 'alice', identity: 'github.user.alice', teams: ['admins'] }
+    change = { identity: 'github.user.alice', action: 'update', desired: desired, current: current }
+    allow(provider_registry).to receive(:fetch).with('github').and_return(provider)
+    allow(provider).to receive(:plan).with(desired: desired, current: current).and_return(ok: false, status: 'error')
+
+    result = described_class.send(:enrich_change, change, provider_registry)
+
+    expect(result).to eq(change)
+  end
+end

data/spec/provider_contract_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::ProviderContract do
+  let(:provider_class) do
+    Class.new do
+      def validate(resource:); end
+      def current(resource:); end
+      def plan(desired:, current:); end
+      def apply(changeset:); end
+    end
+  end
+
+  it 'accepts providers implementing the contract' do
+    provider = provider_class.new
+
+    expect(described_class.validate!(provider)).to eq(provider)
+  end
+
+  it 'raises when required methods are missing' do
+    invalid_provider = Object.new
+
+    expect { described_class.validate!(invalid_provider) }
+      .to raise_error(Umgr::Errors::ProviderContractError, /must implement concrete methods/)
+  end
+
+  it 'raises when provider uses abstract base implementations' do
+    abstract_provider = Umgr::Provider.new
+
+    expect { described_class.validate!(abstract_provider) }
+      .to raise_error(Umgr::Errors::ProviderContractError, /must implement concrete methods/)
+  end
+end

data/spec/provider_registry_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::ProviderRegistry do
+  let(:registry) { described_class.new }
+  let(:provider) do
+    Class.new do
+      def validate(resource:); end
+      def current(resource:); end
+      def plan(desired:, current:); end
+      def apply(changeset:); end
+    end.new
+  end
+
+  it 'registers and fetches providers by normalized name' do
+    registry.register('github', provider)
+
+    expect(registry.fetch(:github)).to eq(provider)
+    expect(registry.fetch('github')).to eq(provider)
+    expect(registry.fetch(:echo)).to be_a(Umgr::Providers::EchoProvider)
+  end
+
+  it 'registers built-in github provider by default' do
+    expect(registry.fetch(:github)).to be_a(Umgr::Providers::GithubProvider)
+  end
+
+  it 'lists registered provider names' do
+    registry.register(:slack, provider)
+    registry.register('github', provider)
+
+    expect(registry.names).to eq(%i[echo github slack])
+  end
+
+  it 'raises for empty provider names' do
+    expect { registry.register(' ', provider) }
+      .to raise_error(Umgr::Errors::ValidationError, /Provider name must be a non-empty/)
+  end
+
+  it 'raises when provider contract is incomplete' do
+    expect { registry.register('github', Object.new) }
+      .to raise_error(Umgr::Errors::ProviderContractError, /must implement/)
+  end
+end

data/spec/provider_resource_validator_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::ProviderResourceValidator do
+  it 'delegates validation to provider for each desired resource' do
+    provider = instance_double(Umgr::Providers::EchoProvider)
+    registry = instance_double(Umgr::ProviderRegistry)
+    desired_state = {
+      resources: [
+        { provider: 'echo', type: 'user', name: 'alice' },
+        { provider: 'echo', type: 'user', name: 'bob' }
+      ]
+    }
+
+    allow(registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:validate)
+
+    described_class.validate!(desired_state: desired_state, provider_registry: registry)
+
+    expect(provider).to have_received(:validate).with(resource: { provider: 'echo', type: 'user', name: 'alice' })
+    expect(provider).to have_received(:validate).with(resource: { provider: 'echo', type: 'user', name: 'bob' })
+  end
+
+  it 'raises when provider returns ok: false validation result' do
+    provider = instance_double(Umgr::Providers::EchoProvider)
+    registry = instance_double(Umgr::ProviderRegistry)
+    desired_state = {
+      resources: [
+        { provider: 'echo', type: 'user', name: 'alice', identity: 'echo.user.alice' }
+      ]
+    }
+
+    allow(registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive(:validate).and_return(ok: false, error: 'provider validation failed')
+
+    expect do
+      described_class.validate!(desired_state: desired_state, provider_registry: registry)
+    end.to raise_error(Umgr::Errors::ValidationError, /provider validation failed for resource echo\.user\.alice/)
+  end
+end

data/spec/provider_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::Provider do
+  subject(:provider) { described_class.new }
+
+  it 'raises for validate by default' do
+    expect { provider.validate(resource: {}) }
+      .to raise_error(Umgr::Errors::AbstractMethodError, /must implement #validate/)
+  end
+
+  it 'raises for current by default' do
+    expect { provider.current(resource: {}) }
+      .to raise_error(Umgr::Errors::AbstractMethodError, /must implement #current/)
+  end
+
+  it 'raises for plan by default' do
+    expect { provider.plan(desired: {}, current: {}) }
+      .to raise_error(Umgr::Errors::AbstractMethodError, /must implement #plan/)
+  end
+
+  it 'raises for apply by default' do
+    expect { provider.apply(changeset: {}) }
+      .to raise_error(Umgr::Errors::AbstractMethodError, /must implement #apply/)
+  end
+end

data/spec/providers/echo_provider_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::Providers::EchoProvider do
+  subject(:provider) { described_class.new }
+
+  let(:resource) do
+    {
+      provider: 'echo',
+      type: 'user',
+      name: 'alice',
+      attributes: {
+        email: 'alice@example.com',
+        team: 'platform'
+      }
+    }
+  end
+
+  it 'echoes resource in validate' do
+    result = provider.validate(resource: resource)
+
+    expect(result[:ok]).to be(true)
+    expect(result[:provider]).to eq('echo')
+    expect(result[:resource]).to eq(resource)
+  end
+
+  it 'echoes account attributes in current' do
+    result = provider.current(resource: resource)
+
+    expect(result[:ok]).to be(true)
+    expect(result[:account]).to eq(email: 'alice@example.com', team: 'platform')
+  end
+
+  it 'returns update status when desired and current differ' do
+    result = provider.plan(desired: { email: 'alice@example.com' }, current: { email: 'old@example.com' })
+
+    expect(result[:ok]).to be(true)
+    expect(result[:status]).to eq('update')
+  end
+
+  it 'returns no_change status when desired and current are the same' do
+    desired = { email: 'alice@example.com' }
+    result = provider.plan(desired: desired, current: desired)
+
+    expect(result[:ok]).to be(true)
+    expect(result[:status]).to eq('no_change')
+  end
+
+  it 'echoes changeset in apply' do
+    result = provider.apply(changeset: { action: 'update' })
+
+    expect(result[:ok]).to be(true)
+    expect(result[:status]).to eq('applied')
+    expect(result[:changeset]).to eq(action: 'update')
+  end
+end

data/spec/providers/github_account_normalizer_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::Providers::GithubAccountNormalizer do
+  it 'normalizes github user payload into canonical account resource shape' do
+    user = {
+      'id' => 10,
+      'login' => 'alice',
+      'avatar_url' => 'https://avatars.example/alice',
+      'html_url' => 'https://github.com/alice',
+      'type' => 'User'
+    }
+
+    result = described_class.call(user: user, org: 'acme', teams: %w[admins platform])
+
+    expect(result).to eq(
+      provider: 'github',
+      type: 'user',
+      name: 'alice',
+      identity: 'github.user.alice',
+      org: 'acme',
+      teams: %w[admins platform],
+      attributes: {
+        id: 10,
+        login: 'alice',
+        avatar_url: 'https://avatars.example/alice',
+        html_url: 'https://github.com/alice',
+        type: 'User'
+      }
+    )
+  end
+end

data/spec/providers/github_api_client_spec.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'json'
+
+RSpec.describe Umgr::Providers::GithubApiClient do
+  subject(:client) { described_class.new }
+
+  it 'paginates org users with link headers' do
+    stub_request(:get, %r{\Ahttps://api\.github\.com/orgs/acme/members(\?.*)?\z}).to_return(
+      status: 200,
+      body: JSON.generate([{ login: 'alice' }]),
+      headers: {
+        'Content-Type' => 'application/json',
+        'Link' => '<https://api.github.com/orgs/acme/members?page=2>; rel="next"'
+      }
+    )
+    stub_request(:get, 'https://api.github.com/orgs/acme/members?page=2').to_return(
+      status: 200,
+      body: JSON.generate([{ login: 'bob' }]),
+      headers: { 'Content-Type' => 'application/json' }
+    )
+
+    result = client.list_org_users(org: 'acme', token: 'secret')
+
+    expect(result.map { |user| user[:login] || user['login'] }).to eq(%w[alice bob])
+  end
+
+  it 'builds team memberships map from org teams and members endpoints' do
+    stub_request(:get, %r{\Ahttps://api\.github\.com/orgs/acme/teams(\?.*)?\z}).to_return(
+      status: 200,
+      body: JSON.generate([{ id: 101, slug: 'platform' }, { id: 102, slug: 'admins' }]),
+      headers: { 'Content-Type' => 'application/json' }
+    )
+    stub_request(:get, %r{\Ahttps://api\.github\.com/teams/101/members(\?.*)?\z}).to_return(
+      status: 200,
+      body: JSON.generate([{ login: 'alice' }, { login: 'bob' }]),
+      headers: { 'Content-Type' => 'application/json' }
+    )
+    stub_request(:get, %r{\Ahttps://api\.github\.com/teams/102/members(\?.*)?\z}).to_return(
+      status: 200,
+      body: JSON.generate([{ login: 'alice' }]),
+      headers: { 'Content-Type' => 'application/json' }
+    )
+
+    result = client.list_org_team_memberships(org: 'acme', token: 'secret')
+
+    expect(result).to eq(
+      'alice' => %w[admins platform],
+      'bob' => ['platform']
+    )
+  end
+
+  it 'raises api error on non-success responses' do
+    stub_request(:get, %r{\Ahttps://api\.github\.com/orgs/acme/members(\?.*)?\z}).to_return(
+      status: 500,
+      body: JSON.generate(message: 'internal error'),
+      headers: { 'Content-Type' => 'application/json' }
+    )
+
+    expect { client.list_org_users(org: 'acme', token: 'secret') }
+      .to raise_error(Umgr::Errors::ApiError, /GitHub API request failed/)
+  end
+
+  it 'invites user to organization membership' do
+    stub_request(:put, 'https://api.github.com/orgs/acme/memberships/alice')
+      .with(body: hash_including(role: 'member'))
+      .to_return(status: 200, body: JSON.generate(state: 'pending'), headers: { 'Content-Type' => 'application/json' })
+
+    result = client.invite_org_member(org: 'acme', login: 'alice', token: 'secret')
+
+    expect(result[:state] || result['state']).to eq('pending')
+  end
+
+  it 'adds and removes team membership by slug' do
+    stub_request(:get, %r{\Ahttps://api\.github\.com/orgs/acme/teams(\?.*)?\z}).to_return(
+      status: 200,
+      body: JSON.generate([{ id: 101, slug: 'platform' }]),
+      headers: { 'Content-Type' => 'application/json' }
+    )
+    stub_request(:put, 'https://api.github.com/teams/101/memberships/alice').to_return(
+      status: 200,
+      body: JSON.generate(state: 'active'),
+      headers: { 'Content-Type' => 'application/json' }
+    )
+    stub_request(:delete, 'https://api.github.com/teams/101/memberships/alice').to_return(status: 204, body: '')
+
+    add_result = client.add_team_membership(org: 'acme', team_slug: 'platform', login: 'alice', token: 'secret')
+    remove_result = client.remove_team_membership(org: 'acme', team_slug: 'platform', login: 'alice', token: 'secret')
+
+    expect(add_result[:state] || add_result['state']).to eq('active')
+    expect(remove_result).to be(true)
+  end
+
+  it 'removes organization membership' do
+    stub_request(:delete, 'https://api.github.com/orgs/acme/memberships/alice').to_return(status: 204, body: '')
+
+    result = client.remove_org_member(org: 'acme', login: 'alice', token: 'secret')
+
+    expect(result).to be(true)
+  end
+end

data/spec/providers/github_plan_builder_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::Providers::GithubPlanBuilder do
+  describe '.call' do
+    it 'plans invite and team membership additions for new users' do
+      result = described_class.call(
+        desired: { provider: 'github', type: 'user', name: 'alice', teams: %w[admins platform] },
+        current: nil
+      )
+
+      expect(result).to include(
+        ok: true,
+        provider: 'github',
+        status: 'planned',
+        organization_action: 'invite'
+      )
+      expect(result.fetch(:operations)).to eq(
+        [
+          { type: 'invite_org_member', login: 'alice' },
+          { type: 'add_team_membership', login: 'alice', team: 'admins' },
+          { type: 'add_team_membership', login: 'alice', team: 'platform' }
+        ]
+      )
+    end
+
+    it 'plans no_change operation when memberships are identical' do
+      result = described_class.call(
+        desired: { provider: 'github', type: 'user', name: 'alice', teams: %w[platform admins] },
+        current: { provider: 'github', type: 'user', name: 'alice', teams: %w[admins platform] }
+      )
+
+      expect(result.fetch(:organization_action)).to eq('keep')
+      expect(result.fetch(:team_actions)).to eq(add: [], remove: [], unchanged: %w[admins platform])
+      expect(result.fetch(:operations)).to eq([{ type: 'no_change', login: 'alice' }])
+    end
+
+    it 'plans org removal when user is not desired anymore' do
+      result = described_class.call(
+        desired: nil,
+        current: { provider: 'github', type: 'user', name: 'alice', teams: ['admins'] }
+      )
+
+      expect(result.fetch(:organization_action)).to eq('remove')
+      expect(result.fetch(:operations)).to eq([{ type: 'remove_org_member', login: 'alice' }])
+    end
+  end
+end