umgr 0.1.4

data/lib/umgr/providers/github_provider.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative 'github/api_client'
+require_relative 'github/apply_executor'
+require_relative 'github/account_normalizer'
+require_relative 'github/plan_builder'
+
+module Umgr
+  module Providers
+    class GithubProvider < Provider
+      def initialize(api_client: nil)
+        super()
+        @api_client = api_client || GithubApiClient.new
+      end
+
+      def validate(resource:)
+        validate_org!(resource)
+        validate_auth!(resource)
+        validate_teams!(resource)
+
+        {
+          ok: true,
+          provider: 'github',
+          resource: resource
+        }
+      end
+
+      def current(resource:)
+        validate(resource: resource)
+        org = resource.fetch(:org)
+        token = resolve_token!(resource)
+        accounts = import_accounts(org: org, token: token)
+        current_result(org: org, accounts: accounts)
+      end
+
+      def current_result(org:, accounts:)
+        {
+          ok: true,
+          provider: 'github',
+          org: org,
+          imported_accounts: accounts,
+          count: accounts.length
+        }
+      end
+
+      def plan(desired:, current:)
+        GithubPlanBuilder.call(desired: desired, current: current)
+      end
+
+      def apply(changeset:)
+        GithubApplyExecutor.call(
+          changeset: changeset,
+          api_client: api_client,
+          token_resolver: method(:resolve_token!),
+          present_string: method(:present_string?),
+          plan_resolver: method(:plan_for_apply)
+        )
+      end
+
+      private
+
+      attr_reader :api_client
+
+      def validate_org!(resource)
+        org = resource[:org]
+        return if org.is_a?(String) && !org.strip.empty?
+
+        raise Errors::ValidationError, 'GitHub provider requires non-empty `org`'
+      end
+
+      def validate_auth!(resource)
+        token = resource[:token]
+        token_env = resource[:token_env]
+        return if present_string?(token) || present_string?(token_env)
+
+        raise Errors::ValidationError, 'GitHub provider requires `token` or `token_env`'
+      end
+
+      def validate_teams!(resource)
+        teams = resource[:teams]
+        return if teams.nil?
+        return if teams.is_a?(Array) && teams.all? { |team| present_string?(team) }
+
+        raise Errors::ValidationError, 'GitHub provider `teams` must be an array of non-empty strings'
+      end
+
+      def present_string?(value)
+        value.is_a?(String) && !value.strip.empty?
+      end
+
+      def resolve_token!(resource)
+        return resource[:token] if present_string?(resource[:token])
+
+        env_name = resource[:token_env]
+        env_token = ENV.fetch(env_name, nil)
+        return env_token if present_string?(env_token)
+
+        raise Errors::ValidationError, "GitHub provider `token_env` #{env_name} is not set"
+      end
+
+      def import_accounts(org:, token:)
+        users = api_client.list_org_users(org: org, token: token)
+        memberships = api_client.list_org_team_memberships(org: org, token: token)
+        users.map do |user|
+          login = fetch_login(user)
+          teams = memberships.fetch(login, [])
+          GithubAccountNormalizer.call(user: user, org: org, teams: teams)
+        end
+      end
+
+      def fetch_login(user)
+        login = user[:login] if user.respond_to?(:[])
+        login ||= user['login'] if user.respond_to?(:[])
+        login ||= user.login if user.respond_to?(:login)
+        return login if present_string?(login)
+
+        raise Errors::ApiError, 'GitHub API response missing user login'
+      end
+
+      def plan_for_apply(desired, current)
+        plan(desired: desired, current: current)
+      end
+    end
+  end
+end

data/lib/umgr/resource_identity.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Umgr
+  module ResourceIdentity
+    module_function
+
+    def call(resource)
+      "#{resource.fetch(:provider)}.#{resource.fetch(:type)}.#{resource.fetch(:name)}"
+    end
+  end
+end

data/lib/umgr/runner.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Umgr
+  class Runner
+    include RunnerConfig
+
+    ACTIONS = %i[init validate plan apply show import].freeze
+
+    def initialize(state_backend: nil, provider_registry: nil)
+      @state_backend = state_backend || StateBackend.new
+      @provider_registry = provider_registry || ProviderRegistry.new
+    end
+
+    def ping = :ok
+
+    # rubocop:disable Style/ArgumentsForwarding
+    def dispatch(action, **options)
+      action_name = action.to_sym
+      raise Errors::UnknownActionError, "Unknown action: #{action}" unless ACTIONS.include?(action_name)
+
+      send(action_name, **options)
+    end
+    # rubocop:enable Style/ArgumentsForwarding
+
+    private
+
+    def init(**options)
+      existing_state = state_backend.read
+      if existing_state
+        completed(:init, 'already_initialized', options, existing_state)
+      else
+        state_backend.write(StateTemplate::INITIAL_STATE)
+        completed(:init, 'initialized', options, StateTemplate::INITIAL_STATE)
+      end
+    end
+
+    def validate(**options)
+      resolved_options = with_resolved_config(:validate, options)
+      not_implemented(:validate, resolved_options)
+    end
+
+    def plan(**options)
+      resolved_options = with_resolved_config(:plan, options)
+      PlanResultBuilder.call(
+        state_backend: state_backend,
+        options: resolved_options,
+        provider_registry: provider_registry
+      )
+    end
+
+    def apply(**options)
+      resolved_options = with_resolved_config(:apply, options)
+      ApplyResultBuilder.call(
+        state_backend: state_backend,
+        options: resolved_options,
+        provider_registry: provider_registry
+      )
+    end
+
+    def show(**options)
+      state = state_backend.read
+      completed(:show, state ? 'ok' : 'not_initialized', options, state)
+    end
+
+    def import(**options)
+      resolved_options = with_resolved_config(:import, options)
+      ImportResultBuilder.call(
+        state_backend: state_backend,
+        options: resolved_options,
+        provider_registry: provider_registry
+      )
+    end
+
+    def not_implemented(action, options)
+      {
+        ok: false,
+        action: action.to_s,
+        status: 'not_implemented',
+        options: options,
+        state_path: state_backend.path
+      }
+    end
+
+    def completed(action, status, options, state)
+      {
+        ok: true,
+        action: action.to_s,
+        status: status,
+        options: options,
+        state_path: state_backend.path,
+        state: state
+      }
+    end
+
+    attr_reader :state_backend, :provider_registry
+  end
+end

data/lib/umgr/runner_config.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Umgr
+  module RunnerConfig
+    AUTO_DISCOVERY_CONFIGS = %w[umgr.yml umgr.yaml umgr.json].freeze
+
+    private
+
+    def with_resolved_config(action, options)
+      resolved_options = options.dup
+      resolved = resolve_config_path(options[:config])
+      if resolved
+        with_validated_config_options(action, resolved_options, resolved)
+      else
+        supported = AUTO_DISCOVERY_CONFIGS.join(', ')
+        raise Errors::ValidationError, "`config` is required for #{action}. Auto-discovery checks: #{supported}"
+      end
+    end
+
+    def with_validated_config_options(action, resolved_options, resolved)
+      desired_state = ensure_valid_config(resolved)
+      UnknownProviderGuard.validate!(desired_state: desired_state, action: action, provider_registry: provider_registry)
+      ProviderResourceValidator.validate!(desired_state: desired_state, provider_registry: provider_registry)
+      resolved_options.merge(config: resolved, desired_state: desired_state)
+    end
+
+    def resolve_config_path(config_path)
+      config_path && !config_path.empty? ? explicit_config_path(config_path) : discover_config_path
+    end
+
+    def explicit_config_path(config_path)
+      absolute_path = File.expand_path(config_path)
+      return absolute_path if File.file?(absolute_path)
+
+      raise Errors::ValidationError, "Config file not found: #{config_path}"
+    end
+
+    def discover_config_path
+      AUTO_DISCOVERY_CONFIGS.each do |candidate|
+        absolute_path = File.expand_path(candidate)
+        return absolute_path if File.file?(absolute_path)
+      end
+
+      nil
+    end
+
+    def ensure_valid_config(config_path)
+      desired_state = DeepSymbolizer.call(ConfigValidator.validated_config(config_path))
+      DesiredStateEnricher.call(desired_state)
+    end
+  end
+end

data/lib/umgr/state_backend.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'securerandom'
+
+module Umgr
+  class StateBackend
+    DEFAULT_STATE_DIR = '.umgr'
+    DEFAULT_STATE_FILE = 'state.json'
+
+    def initialize(root_dir: Dir.pwd, state_dir: DEFAULT_STATE_DIR, state_file: DEFAULT_STATE_FILE)
+      @root_dir = root_dir
+      @state_dir = state_dir
+      @state_file = state_file
+    end
+
+    def path
+      File.join(root_dir, state_dir, state_file)
+    end
+
+    def read
+      return nil unless File.file?(path)
+
+      JSON.parse(File.read(path), symbolize_names: true)
+    end
+
+    def write(state)
+      ensure_state_directory!
+      temp_path = "#{path}.tmp-#{SecureRandom.hex(8)}"
+      write_temp_state_file(temp_path, state)
+      File.rename(temp_path, path)
+      path
+    ensure
+      FileUtils.rm_f(temp_path)
+    end
+
+    def delete
+      FileUtils.rm_f(path)
+      path
+    end
+
+    private
+
+    attr_reader :root_dir, :state_dir, :state_file
+
+    def ensure_state_directory!
+      FileUtils.mkdir_p(File.dirname(path))
+    end
+
+    def write_temp_state_file(temp_path, state)
+      File.open(temp_path, 'w') do |file|
+        file.write(JSON.pretty_generate(state))
+        file.flush
+        file.fsync
+      end
+    end
+  end
+end

data/lib/umgr/state_template.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Umgr
+  module StateTemplate
+    INITIAL_STATE = { version: 1, resources: [].freeze }.freeze
+  end
+end

data/lib/umgr/unknown_provider_guard.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Umgr
+  module UnknownProviderGuard
+    module_function
+
+    def validate!(desired_state:, action:, provider_registry:)
+      resources = desired_state.fetch(:resources, [])
+      providers = resources.map { |resource| resource[:provider] }.uniq
+      unknown_providers = providers.reject { |provider| provider_registry.fetch(provider) }
+
+      return if unknown_providers.empty?
+
+      joined = unknown_providers.map(&:to_s).sort.join(', ')
+      raise Errors::ValidationError, "Unknown provider(s) for #{action}: #{joined}"
+    end
+  end
+end

data/lib/umgr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Umgr
+  VERSION = '0.1.4'
+end

data/lib/umgr.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'umgr/version'
+require_relative 'umgr/errors'
+require_relative 'umgr/config_validator'
+require_relative 'umgr/deep_symbolizer'
+require_relative 'umgr/resource_identity'
+require_relative 'umgr/desired_state_enricher'
+require_relative 'umgr/state_template'
+require_relative 'umgr/change_set_builder'
+require_relative 'umgr/drift_report_builder'
+require_relative 'umgr/plan_result_builder'
+require_relative 'umgr/apply_result_builder'
+require_relative 'umgr/import_result_builder'
+require_relative 'umgr/provider'
+require_relative 'umgr/provider_contract'
+require_relative 'umgr/providers/echo_provider'
+require_relative 'umgr/providers/github_provider'
+require_relative 'umgr/provider_registry'
+require_relative 'umgr/unknown_provider_guard'
+require_relative 'umgr/provider_resource_validator'
+require_relative 'umgr/state_backend'
+require_relative 'umgr/runner_config'
+require_relative 'umgr/runner'
+require_relative 'umgr/cli'
+
+module Umgr
+end

data/spec/apply_result_builder_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::ApplyResultBuilder 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(:persisted_state) do
+    {
+      version: 1,
+      resources: [
+        { provider: 'echo', type: 'user', name: 'alice', identity: 'echo.user.alice', attributes: { team: 'infra' } }
+      ]
+    }
+  end
+  let(:desired_state) do
+    {
+      version: 1,
+      resources: [
+        { provider: 'echo', type: 'user', name: 'alice', identity: 'echo.user.alice', attributes: { team: 'platform' } }
+      ]
+    }
+  end
+
+  before do
+    stored_state = persisted_state
+    allow(state_backend).to receive(:read) { stored_state }
+    allow(state_backend).to receive(:write) { |new_state| stored_state = new_state }
+    allow(state_backend).to receive(:delete)
+    allow(provider_registry).to receive(:fetch).with('echo').and_return(provider)
+    allow(provider).to receive_messages(
+      plan: { ok: true, provider: 'echo', status: 'planned' },
+      apply: { ok: true, provider: 'echo', status: 'applied' }
+    )
+  end
+
+  it 'applies changes and persists desired state' do
+    result = described_class.call(
+      state_backend: state_backend,
+      options: { config: '/tmp/users.yml', desired_state: desired_state },
+      provider_registry: provider_registry
+    )
+
+    expect(result[:ok]).to be(true)
+    expect(result[:status]).to eq('applied')
+    expect(result.fetch(:state)).to eq(version: 1, resources: desired_state[:resources])
+    expect(result.fetch(:apply_results).first.fetch(:status)).to eq('applied')
+    expect(result.fetch(:idempotency)).to eq(
+      checked: true,
+      stable: true,
+      summary: { create: 0, update: 0, delete: 0, no_change: 1 }
+    )
+    expect(state_backend.read).to eq(version: 1, resources: desired_state[:resources])
+  end
+
+  it 'does not persist state if provider apply returns ok: false' do
+    allow(provider).to receive(:apply).and_return(ok: false, error: 'boom')
+
+    expect do
+      described_class.call(
+        state_backend: state_backend,
+        options: { config: '/tmp/users.yml', desired_state: desired_state },
+        provider_registry: provider_registry
+      )
+    end.to raise_error(Umgr::Errors::InternalError, /Provider apply failed/)
+    expect(state_backend).not_to have_received(:write)
+    expect(state_backend).not_to have_received(:delete)
+  end
+
+  it 'skips no_change operations without invoking provider apply' do
+    allow(provider).to receive(:plan).and_return(ok: true, provider: 'echo', status: 'no_change')
+    allow(state_backend).to receive(:read).and_return(version: 1, resources: desired_state[:resources])
+    allow(state_backend).to receive(:write)
+
+    result = described_class.call(
+      state_backend: state_backend,
+      options: { config: '/tmp/users.yml', desired_state: desired_state },
+      provider_registry: provider_registry
+    )
+
+    expect(provider).not_to have_received(:apply)
+    expect(result.fetch(:apply_results).first).to include(action: 'no_change', status: 'skipped')
+    expect(result.fetch(:idempotency).fetch(:stable)).to be(true)
+  end
+
+  it 'rolls back to previous state when post-apply plan still includes changes' do
+    writes = []
+    allow(state_backend).to receive(:read).and_return(persisted_state)
+    allow(state_backend).to receive(:write) { |new_state| writes << new_state }
+
+    expect do
+      described_class.call(
+        state_backend: state_backend,
+        options: { config: '/tmp/users.yml', desired_state: desired_state },
+        provider_registry: provider_registry
+      )
+    end.to raise_error(Umgr::Errors::InternalError, /Apply is not idempotent/)
+    expect(writes).to eq([{ version: 1, resources: desired_state[:resources] }, persisted_state])
+    expect(state_backend).not_to have_received(:delete)
+  end
+
+  it 'removes written state on rollback when no previous state existed' do
+    allow(state_backend).to receive(:read).and_return(nil)
+    allow(state_backend).to receive(:write)
+
+    expect do
+      described_class.call(
+        state_backend: state_backend,
+        options: { config: '/tmp/users.yml', desired_state: desired_state },
+        provider_registry: provider_registry
+      )
+    end.to raise_error(Umgr::Errors::InternalError, /Apply is not idempotent/)
+    expect(state_backend).to have_received(:delete).once
+  end
+
+  it 'preserves original error when rollback itself fails' do
+    write_count = 0
+    allow(state_backend).to receive(:read).and_return(persisted_state)
+    allow(state_backend).to receive(:write) do
+      write_count += 1
+      raise Errno::ENOSPC, 'disk full during rollback' if write_count == 2
+    end
+    allow(described_class).to receive(:warn)
+
+    expect do
+      described_class.call(
+        state_backend: state_backend,
+        options: { config: '/tmp/users.yml', desired_state: desired_state },
+        provider_registry: provider_registry
+      )
+    end.to raise_error(Umgr::Errors::InternalError, /Apply is not idempotent/)
+    expect(state_backend).not_to have_received(:delete)
+    expect(described_class).to have_received(:warn).with(/Rollback failed after apply error/)
+  end
+
+  it 'raises internal error when change does not include provider information' do
+    change = { identity: 'missing.provider', action: 'update', desired: nil, current: nil }
+
+    expect do
+      described_class.send(:apply_change, change, provider_registry)
+    end.to raise_error(Umgr::Errors::InternalError, /Missing provider/)
+  end
+end

data/spec/change_set_builder_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+RSpec.describe Umgr::ChangeSetBuilder do
+  it 'generates create, update, delete, and no_change entries with summary' do
+    desired_resources = [
+      { identity: 'echo.user.alice', provider: 'echo', type: 'user', name: 'alice', attributes: { team: 'platform' } },
+      { identity: 'echo.user.carla', provider: 'echo', type: 'user', name: 'carla' },
+      { identity: 'echo.user.dana', provider: 'echo', type: 'user', name: 'dana' }
+    ]
+    current_resources = [
+      { identity: 'echo.user.alice', provider: 'echo', type: 'user', name: 'alice', attributes: { team: 'infra' } },
+      { identity: 'echo.user.bob', provider: 'echo', type: 'user', name: 'bob' },
+      { identity: 'echo.user.dana', provider: 'echo', type: 'user', name: 'dana' }
+    ]
+
+    result = described_class.call(desired_resources: desired_resources, current_resources: current_resources)
+
+    expect(result[:changes].map { |change| [change[:identity], change[:action]] }).to eq(
+      [
+        ['echo.user.alice', 'update'],
+        ['echo.user.bob', 'delete'],
+        ['echo.user.carla', 'create'],
+        ['echo.user.dana', 'no_change']
+      ]
+    )
+    expect(result[:summary]).to eq(create: 1, update: 1, delete: 1, no_change: 1)
+  end
+end