umgr 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c6a035227d1794848fc7c3d1b56d2473a49244eeb03f2cdcae92ed1a28f4f8f
+  data.tar.gz: c90802e37826aeefd96c67142858af3471ef3d070b8b94b39312073268aea464
+SHA512:
+  metadata.gz: 8c3112bba7f1d99878451f440f35b38e4d4e6bbfe80bd6957d06350a051b1ddc6bd82c6e094519839dcde6e22e65109c8a855d72b09facd8cc88d067762aea54
+  data.tar.gz: 9f04bf54461647a171d8f6d99c916a49df34ee88a6741ead03c7d520b7ff393ba57b4fb1af5381aa029ef3805d07e79a8ad8c04f1215d70e11834f6d409537f7

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'aruba'
+  gem 'rake', '~> 13.3'
+  gem 'rspec'
+  gem 'rubocop', require: false
+  gem 'rubocop-performance', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov', require: false
+  gem 'webmock'
+end

data/README.md

@@ -0,0 +1,126 @@
+# umgr
+
+[![checks](https://github.com/gowda/umgr/actions/workflows/checks.yml/badge.svg)](https://github.com/gowda/umgr/actions/workflows/checks.yml)
+[![CodeQL Advanced](https://github.com/gowda/umgr/actions/workflows/codeql.yml/badge.svg)](https://github.com/gowda/umgr/actions/workflows/codeql.yml)
+
+`umgr` is a declarative account lifecycle tool for managing user account state
+across platforms with a desired-state workflow.
+
+You declare desired state in a YAML or JSON configuration file, and `umgr`
+compares it with tracked current state to detect drift, import current users,
+and generate/apply changes.
+
+## Motivation
+
+Organizations often need to keep user accounts consistent across many systems.
+`umgr` provides one interface to define account intent and reconcile drift.
+
+Examples of platforms include Google Workspace, Atlassian, GitHub, Slack, AWS,
+Azure, and Sentry. This list is illustrative, not exhaustive.
+
+## Interfaces
+
+`umgr` exposes two interfaces:
+
+- CLI for operators (built with Thor)
+- Ruby gem API for embedding in larger applications
+
+## Core Capabilities
+
+- Drift detection between desired state and platform/user reality.
+- Import of current users from providers/plugins as a baseline state.
+- Declarative plan/apply workflow for account lifecycle changes.
+
+## Provider/Plugin Model
+
+Each platform integration is implemented as a provider/plugin.
+
+- Providers implement platform-specific sync logic with SDKs or REST APIs.
+- Providers can expose additional provider-specific options on top of the core
+  interface.
+- The first built-in test provider is `echo`, which returns a fake user account
+  by echoing configured attributes.
+
+Provider authoring guide:
+[`docs/provider-authoring.md`](docs/provider-authoring.md)
+
+Website:
+- Site entrypoint: [`docs/index.html`](docs/index.html)
+- Local preview/edit guide: [`docs/website.md`](docs/website.md)
+
+## Configuration and State
+
+- Configuration formats: YAML and JSON
+- Model: desired state (config) + current state reference (tool-managed state)
+- Core identity convention: `provider.type.name`
+
+## CLI Example
+
+```bash
+umgr init
+umgr validate --config examples/users.yml
+umgr plan --config examples/users.yml
+umgr apply --config examples/users.yml
+umgr show
+```
+
+## Ruby API Example
+
+```ruby
+require "umgr"
+
+runner = Umgr::Runner.new
+result = runner.dispatch(:plan, config: "examples/users.yml")
+
+puts result[:ok]
+puts result.dig(:changeset, :summary)
+```
+
+## Private Installation (GitHub Packages)
+
+`umgr` pre-releases are published to GitHub Packages (`rubygems`).
+
+1. Create a GitHub token with:
+- `read:packages`
+- `repo` (required when the package repository is private)
+
+2. Configure RubyGems credentials:
+
+```bash
+mkdir -p ~/.gem
+cat > ~/.gem/credentials <<'EOF'
+---
+:github: Bearer <YOUR_GITHUB_TOKEN>
+EOF
+chmod 0600 ~/.gem/credentials
+```
+
+3. Install directly:
+
+```bash
+gem install umgr \
+  --source "https://rubygems.pkg.github.com/gowda" \
+  --key github
+```
+
+### Gemfile Usage (Private Package)
+
+```ruby
+source "https://rubygems.org"
+source "https://rubygems.pkg.github.com/gowda" do
+  gem "umgr"
+end
+```
+
+Configure Bundler authentication for GitHub Packages:
+
+```bash
+bundle config set --global rubygems.pkg.github.com "<GITHUB_USERNAME>:<YOUR_GITHUB_TOKEN>"
+```
+
+## Public RubyGems Release Path (OIDC)
+
+Public RubyGems publishing is gated behind OIDC trusted publishing readiness.
+
+- Workflow: `.github/workflows/publish-rubygems.yml`
+- Readiness + promotion doc: [`docs/release-rubygems-oidc.md`](docs/release-rubygems-oidc.md)

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'

data/exe/umgr

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'umgr'
+
+Umgr::CLI.start(ARGV)

data/lib/umgr/apply_result_builder.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Umgr
+  # rubocop:disable Metrics/ModuleLength
+  module ApplyResultBuilder
+    module_function
+
+    def call(state_backend:, options:, provider_registry:)
+      previous_state = state_backend.read
+      state_written = false
+      write_state_and_build_result(state_backend, options, provider_registry) { state_written = true }
+    rescue StandardError => e
+      attempt_rollback(state_backend, previous_state) if state_written
+      raise e
+    end
+
+    def apply_changes(changes, provider_registry)
+      changes.map { |change| apply_change(change, provider_registry) }
+    end
+
+    def apply_change(change, provider_registry)
+      return skipped_change_result(change) if change[:action] == 'no_change'
+
+      provider_name = provider_name_for(change)
+      raise Errors::InternalError, "Missing provider for #{change.fetch(:identity)}" unless provider_name
+
+      provider_result = provider_registry.fetch(provider_name).apply(changeset: change)
+      ensure_successful_apply!(provider_result, change)
+      applied_change_result(change, provider_name, provider_result)
+    end
+
+    def skipped_change_result(change)
+      {
+        identity: change.fetch(:identity),
+        action: change.fetch(:action),
+        status: 'skipped'
+      }
+    end
+
+    def ensure_successful_apply!(provider_result, change)
+      return unless apply_failed?(provider_result)
+
+      message = provider_result[:error] || provider_result['error'] || 'unknown provider apply failure'
+      raise Errors::InternalError, "Provider apply failed for #{change.fetch(:identity)}: #{message}"
+    end
+
+    def apply_failed?(provider_result)
+      return false unless provider_result.is_a?(Hash)
+
+      provider_result.fetch(:ok, provider_result.fetch('ok', true)) == false
+    end
+
+    def provider_name_for(change)
+      resource = change[:desired] || change[:current]
+      return nil unless resource
+
+      resource[:provider] || resource['provider']
+    end
+
+    def build_final_state(desired_state)
+      {
+        version: desired_state.fetch(:version),
+        resources: desired_state.fetch(:resources)
+      }
+    end
+
+    def write_state_and_build_result(state_backend, options, provider_registry)
+      desired_state = options.fetch(:desired_state)
+      plan_result = plan_result_for(state_backend, options, provider_registry)
+      apply_results = apply_changes(plan_result.fetch(:changeset).fetch(:changes), provider_registry)
+      final_state = build_final_state(desired_state)
+      state_backend.write(final_state)
+      yield if block_given?
+      idempotency = verify_idempotency(state_backend, options, provider_registry)
+      payload = result_payload(plan_result, apply_results, idempotency)
+      build_result(options: options, state_backend: state_backend, final_state: final_state, payload: payload)
+    end
+
+    def plan_result_for(state_backend, options, provider_registry)
+      PlanResultBuilder.call(state_backend: state_backend, options: options, provider_registry: provider_registry)
+    end
+
+    def rollback_state(state_backend, previous_state)
+      if previous_state
+        state_backend.write(previous_state)
+      else
+        state_backend.delete
+      end
+    end
+
+    def attempt_rollback(state_backend, previous_state)
+      rollback_state(state_backend, previous_state)
+    rescue StandardError => e
+      warn(
+        "Rollback failed after apply error (#{e.class}: #{e.message}); " \
+        'original apply error preserved'
+      )
+    end
+
+    def applied_change_result(change, provider_name, provider_result)
+      {
+        identity: change.fetch(:identity),
+        action: change.fetch(:action),
+        provider: provider_name.to_s,
+        status: 'applied',
+        provider_result: provider_result
+      }
+    end
+
+    def verify_idempotency(state_backend, options, provider_registry)
+      post_apply_plan = plan_result_for(state_backend, options, provider_registry)
+      summary = post_apply_plan.fetch(:changeset).fetch(:summary)
+      return { checked: true, stable: true, summary: summary } if idempotent_summary?(summary)
+
+      raise Errors::InternalError, "Apply is not idempotent; pending changes remain: #{summary}"
+    end
+
+    def idempotent_summary?(summary)
+      summary.fetch(:create).zero? && summary.fetch(:update).zero? && summary.fetch(:delete).zero?
+    end
+
+    def result_payload(plan_result, apply_results, idempotency)
+      {
+        changeset: plan_result.fetch(:changeset),
+        drift: plan_result.fetch(:drift),
+        apply_results: apply_results,
+        idempotency: idempotency
+      }
+    end
+
+    def build_result(options:, state_backend:, final_state:, payload:)
+      base_result(options, state_backend, final_state).merge(
+        payload
+      )
+    end
+
+    def base_result(options, state_backend, final_state)
+      {
+        ok: true,
+        action: 'apply',
+        status: 'applied',
+        options: options,
+        state_path: state_backend.path,
+        state: final_state
+      }
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/umgr/change_set_builder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Umgr
+  module ChangeSetBuilder
+    ACTIONS = %w[create update delete no_change].freeze
+
+    module_function
+
+    def call(desired_resources:, current_resources:)
+      desired_index = index_resources(desired_resources)
+      current_index = index_resources(current_resources)
+      identities = (desired_index.keys + current_index.keys).uniq.sort
+      changes = build_changes(identities, desired_index, current_index)
+      {
+        changes: changes,
+        summary: summarize(changes)
+      }
+    end
+
+    def build_changes(identities, desired_index, current_index)
+      identities.map do |identity|
+        desired = desired_index[identity]
+        current = current_index[identity]
+        {
+          identity: identity,
+          action: action_for(desired: desired, current: current),
+          desired: desired,
+          current: current
+        }
+      end
+    end
+
+    def action_for(desired:, current:)
+      return 'create' if desired && !current
+      return 'delete' if current && !desired
+      return 'no_change' if desired == current
+
+      'update'
+    end
+
+    def summarize(changes)
+      ACTIONS.to_h { |action| [action.to_sym, changes.count { |change| change[:action] == action }] }
+    end
+
+    def index_resources(resources)
+      resources.to_h { |resource| [resource.fetch(:identity), resource] }
+    end
+  end
+end

data/lib/umgr/cli.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'thor'
+
+module Umgr
+  class CLI < Thor
+    desc 'version', 'Print umgr version'
+    def version
+      puts Umgr::VERSION
+    end
+
+    desc 'help [COMMAND]', 'Describe available commands or one specific command'
+    def help(command = nil)
+      super
+    end
+
+    desc 'init', 'Initialize umgr state'
+    def init
+      execute(:init)
+    end
+
+    desc 'validate', 'Validate configuration'
+    option :config, type: :string, desc: 'Path to config file'
+    def validate
+      execute(:validate, **command_options)
+    end
+
+    desc 'plan', 'Generate plan from desired state'
+    option :config, type: :string, desc: 'Path to config file'
+    option :json, type: :boolean, default: false, desc: 'Render plan output as JSON'
+    def plan
+      execute(:plan, **command_options)
+    end
+
+    desc 'apply', 'Apply desired state'
+    option :config, type: :string, desc: 'Path to config file'
+    def apply
+      execute(:apply, **command_options)
+    end
+
+    desc 'show', 'Show current state'
+    def show
+      execute(:show)
+    end
+
+    desc 'import', 'Import current users from providers'
+    option :config, type: :string, desc: 'Path to config file'
+    def import
+      execute(:import, **command_options)
+    end
+
+    private
+
+    def runner
+      @runner ||= Umgr::Runner.new
+    end
+
+    def command_options
+      options.to_h.transform_keys(&:to_sym)
+    end
+
+    def render_result(action, result, options)
+      return render_plan_result(result, options) if action == :plan
+
+      puts JSON.generate(result)
+    end
+
+    def render_plan_result(result, options)
+      return puts(JSON.generate(result)) if options[:json]
+
+      puts drift_status_line(result.fetch(:drift))
+      summary = result.fetch(:changeset).fetch(:summary)
+      puts plan_summary_line(summary)
+      render_plan_changes(result.fetch(:changeset).fetch(:changes))
+    end
+
+    def execute(action, **options)
+      render_result(action, runner.dispatch(action, **options), options)
+    rescue Errors::Error => e
+      render_error(e)
+      exit(e.exit_code)
+    rescue StandardError => e
+      internal = Errors::InternalError.new(e.message)
+      render_error(internal)
+      exit(internal.exit_code)
+    end
+
+    def plan_summary_line(summary)
+      "Plan summary: create=#{summary.fetch(:create)} update=#{summary.fetch(:update)} " \
+        "delete=#{summary.fetch(:delete)} no_change=#{summary.fetch(:no_change)}"
+    end
+
+    def render_plan_changes(changes)
+      changes.each do |change|
+        puts "#{change.fetch(:action).upcase} #{change.fetch(:identity)}"
+      end
+    end
+
+    def drift_status_line(drift)
+      detected = drift.fetch(:detected) ? 'yes' : 'no'
+      "Drift detected: #{detected} (changes=#{drift.fetch(:change_count)})"
+    end
+
+    def render_error(error)
+      warn JSON.generate(
+        {
+          ok: false,
+          error: {
+            type: error.class.name,
+            message: error.message
+          }
+        }
+      )
+    end
+  end
+end

data/lib/umgr/config_validator.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module Umgr
+  class ConfigValidator
+    REQUIRED_TOP_LEVEL_KEYS = %w[version resources].freeze
+    REQUIRED_RESOURCE_FIELDS = %w[provider type name].freeze
+
+    def self.validated_config(config_path)
+      new(config_path).validated_config
+    end
+
+    def self.validate!(config_path)
+      new(config_path).validate!
+    end
+
+    def initialize(config_path)
+      @config_path = config_path
+    end
+
+    def validated_config
+      parsed = parse
+      validate_root!(parsed)
+      validate_resources!(parsed['resources'])
+      parsed
+    end
+
+    def validate!
+      validated_config
+      nil
+    end
+
+    private
+
+    attr_reader :config_path
+
+    def parse
+      content = File.read(config_path)
+      parse_by_extension(content)
+    rescue JSON::ParserError, Psych::SyntaxError => e
+      raise Errors::ValidationError, "Config parse error in #{config_path}: #{e.message}"
+    end
+
+    def parse_by_extension(content)
+      case File.extname(config_path).downcase
+      when '.json'
+        JSON.parse(content)
+      when '.yml', '.yaml'
+        YAML.safe_load(content, aliases: false)
+      else
+        raise Errors::ValidationError, "Unsupported config format: #{config_path}"
+      end
+    end
+
+    def validate_root!(parsed)
+      raise Errors::ValidationError, "Config root must be an object in #{config_path}" unless parsed.is_a?(Hash)
+
+      REQUIRED_TOP_LEVEL_KEYS.each do |key|
+        next if parsed.key?(key)
+
+        raise Errors::ValidationError, "Missing required key `#{key}` in #{config_path}"
+      end
+
+      version = parsed['version']
+      return if version.is_a?(Integer) && version.positive?
+
+      raise Errors::ValidationError, "`version` must be a positive integer in #{config_path}"
+    end
+
+    def validate_resources!(resources)
+      raise Errors::ValidationError, "`resources` must be an array in #{config_path}" unless resources.is_a?(Array)
+
+      resources.each_with_index do |resource, index|
+        validate_resource!(resource, index)
+      end
+    end
+
+    def validate_resource!(resource, index)
+      unless resource.is_a?(Hash)
+        raise Errors::ValidationError, "Resource at index #{index} must be an object in #{config_path}"
+      end
+
+      REQUIRED_RESOURCE_FIELDS.each do |field|
+        value = resource[field]
+        next if value.is_a?(String) && !value.empty?
+
+        raise Errors::ValidationError, "Resource #{index} missing required string field `#{field}` in #{config_path}"
+      end
+    end
+  end
+end

data/lib/umgr/deep_symbolizer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Umgr
+  module DeepSymbolizer
+    module_function
+
+    def call(value)
+      case value
+      when Hash
+        symbolize_hash(value)
+      when Array
+        value.map { |item| call(item) }
+      else
+        value
+      end
+    end
+
+    def symbolize_hash(value)
+      value.each_with_object({}) do |(key, nested_value), memo|
+        symbol_key = key.is_a?(String) ? key.to_sym : key
+        memo[symbol_key] = call(nested_value)
+      end
+    end
+  end
+end

data/lib/umgr/desired_state_enricher.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Umgr
+  module DesiredStateEnricher
+    module_function
+
+    def call(desired_state)
+      resources = desired_state.fetch(:resources, []).map do |resource|
+        resource.merge(identity: ResourceIdentity.call(resource))
+      end
+
+      desired_state.merge(resources: resources)
+    end
+  end
+end

data/lib/umgr/drift_report_builder.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Umgr
+  module DriftReportBuilder
+    DRIFT_ACTIONS = %i[create update delete].freeze
+
+    module_function
+
+    def call(summary)
+      drift_counts = DRIFT_ACTIONS.to_h { |action| [action, summary.fetch(action, 0)] }
+      change_count = drift_counts.values.sum
+      {
+        detected: change_count.positive?,
+        change_count: change_count,
+        actions: drift_counts
+      }
+    end
+  end
+end

data/lib/umgr/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Umgr
+  module Errors
+    class Error < StandardError
+      EXIT_CODE = 1
+
+      def exit_code
+        self.class::EXIT_CODE
+      end
+    end
+
+    class ValidationError < Error
+      EXIT_CODE = 2
+    end
+
+    class UnknownActionError < Error
+      EXIT_CODE = 3
+    end
+
+    class InternalError < Error
+      EXIT_CODE = 70
+    end
+
+    class ApiError < Error
+      EXIT_CODE = InternalError::EXIT_CODE
+    end
+
+    class AbstractMethodError < Error
+    end
+
+    class ProviderContractError < Error
+      EXIT_CODE = ValidationError::EXIT_CODE
+    end
+  end
+end