command_tower 0.10.0 → 0.11.0

data/app/services/command_tower/messaging/execution/operation_logger.rb

@@ -228,7 +228,7 @@ module CommandTower
               payload[:channel_delivery_id] = channel_delivery_id
             end
 
-            Contract::Observability::StructuredLogger.public_send(level, payload)
+            Contract::Observability::Publisher.public_send(level, payload)
           end
         end
       end

data/app/services/command_tower/messaging/handoff/operation_logger.rb

@@ -69,7 +69,7 @@ module CommandTower
               payload[:communication_id] = communication_id
             end
 
-            Contract::Observability::StructuredLogger.public_send(level, payload)
+            Contract::Observability::Publisher.public_send(level, payload)
           end
         end
       end

data/app/services/command_tower/messaging/inbox/operation_logger.rb

@@ -15,7 +15,7 @@ module CommandTower
         class << self
           def lifecycle_changed(operation:, item:, bulk: false)
             event = EVENT_BY_OPERATION.fetch(operation)
-            Contract::Observability::StructuredLogger.info(
+            Contract::Observability::Publisher.info(
               event:,
               messaging_operation: "inbox",
               operation: operation.to_s,

data/app/services/command_tower/messaging/planner/operation_logger.rb

@@ -11,7 +11,7 @@ module CommandTower
             channel_key:,
             reason_codes:
           )
-            Contract::Observability::StructuredLogger.info(
+            Contract::Observability::Publisher.info(
               event: "messaging.planner.readiness_excluded",
               correlation_id: Contract::Observability::Correlation.resolve,
               messaging_operation: "planner",

data/app/services/command_tower/messaging/recipient_readiness/evaluate.rb

@@ -299,7 +299,7 @@ module CommandTower
         end
 
         def log_evaluation(result)
-          Contract::Observability::StructuredLogger.info(
+          Contract::Observability::Publisher.info(
             event: "messaging.recipient_readiness.evaluated",
             recipient_id: @recipient_id,
             channel_key: result.channel_key,

data/app/services/command_tower/service_base.rb

@@ -19,6 +19,8 @@ class CommandTower::ServiceBase
   include Interactor
   include CommandTower::ServiceLogging
   include CommandTower::ArgumentValidation
+  include CommandTower::Execution::ContextAccess
+  include CommandTower::Logging::LifecycleDeclaration
 
   ON_ARGUMENT_VALIDATION = [
     DEFAULT_VALIDATION = :raise,
@@ -27,11 +29,10 @@ class CommandTower::ServiceBase
   ]
 
   def self.inherited(subclass)
-    # Add the base logging to the subclass.
-    # Since this is done at inheritance time it should always be the first and last hook to run.
-    subclass.around(:service_base_logging)
     subclass.around(:internal_validate)
     subclass.after(:sanitize_params)
+    # Registered last so Interactor treats it as the outermost around (reverse nest).
+    subclass.around(:command_tower_lifecycle)
   end
 
   def validate!
@@ -39,51 +40,37 @@ class CommandTower::ServiceBase
   end
 
   def internal_validate(interactor)
-    # call validate that is overridden from child
-    begin
-      validate! # custom validations defined on the child class
-      run_validations! # ArgumentValidation's based on defined settings on child
-    rescue StandardError => e
-      log_error("Error during validation. #{e.message}")
-      raise
-    end
-
-    # call interactor
+    validate! # custom validations defined on the child class
+    run_validations! # ArgumentValidation's based on defined settings on child
     interactor.call
   end
 
-  def service_base_logging(interactor)
-    beginning_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-    # Pre processing stats
-    log_info("Start")
-
-    # Run the job!
-    interactor.call
-
-    # Set status for use in ensure block
-    status = :complete
-
-  # Capture Interactor::Failure for logging purposes, then reraise
-  rescue ::Interactor::Failure
-    # set status for use in ensure block
-    status = :failure
+  def command_tower_lifecycle(interactor)
+    CommandTower::Events.around_execution(layer: :service, subject: self.class.name, log_lifecycle: self.class.lifecycle_loggable?) do |record|
+      begin
+        interactor.call
+        record[:result] = :success
+      rescue ::Interactor::Failure
+        record[:result] = :failure
+        record[:error_codes] = service_lifecycle_error_codes
+        record[:log_level] = service_lifecycle_log_level
+        raise
+      rescue ::Exception => e
+        record[:unexpected] = e
+        raise
+      end
+    end
+  end
 
-    # Re-raise to let the core Interactor handle this
-    raise
-  # Capture exception explicitly for logging purposes, then reraise
-  rescue ::Exception => e
-    # set status for use in ensure block
-    status = :error
+  def service_lifecycle_error_codes
+    error = context.application_error if context.respond_to?(:application_error)
+    return [error.code] if error.respond_to?(:code)
 
-    # Log error
-    log_error("Error #{e.class.name}")
+    nil
+  end
 
-    raise
-  ensure
-    # Always log how long it took along with a status
-    finished_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    elapsed = ((finished_time - beginning_time) * 1000).round(2)
-    log_info("Finished with [#{status}]...elapsed #{elapsed}ms")
+  def service_lifecycle_log_level
+    error = context.application_error if context.respond_to?(:application_error)
+    error.log_level if error.respond_to?(:log_level)
   end
 end

data/app/services/command_tower/service_logging.rb

@@ -1,41 +1,7 @@
 # frozen_string_literal: true
 
 module CommandTower::ServiceLogging
-  def log_info(msg)
-    log(level: :info, msg:)
-  end
-
-  def log_warn(msg)
-    log(level: :warn, msg:)
-  end
-
-  def log_error(msg)
-    log(level: :error, msg:)
-  end
-
-  def log(level:, msg:)
-    logger.public_send(level, aletered_message(msg))
-  rescue StandardError
-    Rails.logger.public_send(level, aletered_message(msg))
-  end
-
-  def aletered_message(msg)
-    "#{log_prefix}: #{msg}"
-  end
-
-  def logger
-    defined?(context) ? context.logger : Rails.logger
-  end
-
-  def log_prefix
-    "[#{class_name}-#{service_id}]"
-  end
-
-  def class_name
-    self.class.name
-  end
-
-  def service_id
-    @service_id ||= SecureRandom.alphanumeric(10)
+  def self.included(base)
+    base.include CommandTower::Execution::ContextAccess
   end
 end

data/app/services/command_tower/services/account/clear_phone.rb

@@ -13,10 +13,18 @@ module CommandTower
             return
           end
 
+          previous = user.phone_number
           user.phone_number = nil
           user.phone_number_validated = false
           user.save!
 
+          audit(
+            :phone_cleared,
+            subject: user,
+            affected_user: user,
+            changes: { phone: { from: previous, to: nil } }
+          )
+
           context.user = user
         end
       end

data/app/services/command_tower/services/account/phone_verification/verify.rb

@@ -36,6 +36,7 @@ module CommandTower
 
               locked.update!(phone_number_validated: true)
               CommandTower::Secrets::Cleanse.(user: locked, reason: CommandTower::Secrets::PHONE_VERIFICATION)
+              audit(:phone_verified, subject: locked, affected_user: locked, changes: {})
               context.user = locked.reload
               context.already_verified = false
             end

data/app/services/command_tower/services/account/update_phone.rb

@@ -10,7 +10,7 @@ module CommandTower
         validate :user, is_a: User, required: true
         validate :phone_number, is_a: String, required: true
 
-        def call
+          def call
           normalized = normalize
 
           if user.phone_number == normalized
@@ -18,6 +18,7 @@ module CommandTower
             return
           end
 
+          previous = user.phone_number
           user.phone_number = normalized
           user.phone_number_validated = false
 
@@ -27,6 +28,13 @@ module CommandTower
             reject!(DUPLICATE_MESSAGE)
           end
 
+          audit(
+            :phone_updated,
+            subject: user,
+            affected_user: user,
+            changes: { phone: { from: previous, to: normalized } }
+          )
+
           context.user = user
         end
 

data/app/services/command_tower/services/admin/users.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Admin
+      module Users
+        class List < CommandTower::Services::ApplicationService
+          validate :limit, is_a: Integer, required: true, gte: 1, lte: 100
+          validate :offset, is_a: Integer, required: true, gt: -1
+          validate :search, is_a: String, required: false
+          validate :principal, is_a: User, required: false
+          validate :scope_context, is_a: [CommandTower::AdminScope::ScopeContext, NilClass], required: false
+
+          def call
+            relation = ::User.order(id: :desc)
+            relation = CommandTower::AdminScope::ApplyUsersNarrowing.call(
+              relation:,
+              scope_context:,
+              principal: principal || scope_context_principal
+            )
+            relation = apply_search(relation)
+
+            context.users = relation.limit(limit).offset(offset).to_a
+            context.pagination = { limit:, offset:, total_count: relation.count }
+          end
+
+          private
+
+          def scope_context_principal
+            principal
+          end
+
+          def apply_search(relation)
+            token = search.to_s.strip
+            return relation if token.empty?
+
+            pattern = "%#{ActiveRecord::Base.sanitize_sql_like(token)}%"
+            relation.where(
+              "email LIKE :q OR username LIKE :q OR first_name LIKE :q OR last_name LIKE :q",
+              q: pattern
+            )
+          end
+        end
+
+        class Show < CommandTower::Services::ApplicationService
+          validate :id, is_a: Integer, required: true
+          validate :principal, is_a: User, required: false
+          validate :scope_context, is_a: [CommandTower::AdminScope::ScopeContext, NilClass], required: false
+
+          def call
+            relation = ::User.where(id:)
+            relation = CommandTower::AdminScope::ApplyUsersNarrowing.call(
+              relation:,
+              scope_context:,
+              principal: principal || scope_context_principal
+            )
+            user = relation.first
+            if user.nil?
+              return context.fail!(application_error: CommandTower::Errors::NotFoundError.new)
+            end
+
+            context.user = user
+          end
+
+          private
+
+          def scope_context_principal
+            principal
+          end
+        end
+
+        module IdentityUniqueness
+          DUPLICATE_MESSAGE = "has already been taken"
+
+          module_function
+
+          def uniqueness_error(field)
+            CommandTower::Errors::ValidationError.new(details: { field => DUPLICATE_MESSAGE })
+          end
+
+          def uniqueness_taken?(error, attribute)
+            record = error.respond_to?(:record) ? error.record : nil
+            return false if record.nil?
+
+            Array(record.errors.details[attribute]).any? { |entry| entry[:error] == :taken }
+          end
+        end
+
+        class UpdateName < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :first_name, is_a: String, required: true
+          validate :last_name, is_a: String, required: true
+
+          def call
+            normalized_first = first_name.to_s.strip
+            normalized_last = last_name.to_s.strip
+            first_changed = normalized_first != user.first_name.to_s
+            last_changed = normalized_last != user.last_name.to_s
+
+            unless first_changed || last_changed
+              context.user = user
+              context.changed = false
+              return
+            end
+
+            application_error = nil
+
+            ActiveRecord::Base.transaction do
+              if first_changed
+                application_error = mutate(first_name: normalized_first)
+                raise ActiveRecord::Rollback if application_error
+              end
+
+              if last_changed
+                application_error = mutate(last_name: normalized_last)
+                raise ActiveRecord::Rollback if application_error
+              end
+            end
+
+            if application_error
+              context.fail!(application_error:)
+              return
+            end
+
+            context.user = user.reload
+            context.changed = true
+          end
+
+          private
+
+          def mutate(**attribute)
+            result = CommandTower::UserAttributes::Mutate.call(user:, **attribute)
+            return nil if result.success?
+
+            details = result.invalid_argument_hash.transform_values { _1[:msg].to_s }
+            CommandTower::Errors::ValidationError.new(details: camelize_detail_keys(details))
+          rescue ActiveRecord::RecordInvalid => error
+            uniqueness_or_raise(error, attribute.keys.first)
+          rescue ActiveRecord::RecordNotUnique
+            IdentityUniqueness.uniqueness_error(camelize_field(attribute.keys.first))
+          end
+
+          def uniqueness_or_raise(error, attribute)
+            if IdentityUniqueness.uniqueness_taken?(error, attribute)
+              return IdentityUniqueness.uniqueness_error(camelize_field(attribute))
+            end
+
+            raise error
+          end
+
+          def camelize_detail_keys(details)
+            details.transform_keys { |key| camelize_field(key) }
+          end
+
+          def camelize_field(field)
+            case field.to_s
+            when "first_name" then "firstName"
+            when "last_name" then "lastName"
+            else field.to_s
+            end
+          end
+        end
+
+        class UpdateUsername < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :username, is_a: String, required: true
+
+          def call
+            normalized = username.to_s.strip
+            if user.username.to_s == normalized
+              context.user = user
+              context.changed = false
+              return
+            end
+
+            result = CommandTower::UserAttributes::Mutate.call(user:, username: normalized)
+            unless result.success?
+              details = result.invalid_argument_hash.transform_values { _1[:msg].to_s }
+              context.fail!(application_error: CommandTower::Errors::ValidationError.new(details:))
+              return
+            end
+
+            context.user = user.reload
+            context.changed = true
+          rescue ActiveRecord::RecordInvalid => error
+            fail_uniqueness_or_raise(error)
+          rescue ActiveRecord::RecordNotUnique
+            context.fail!(application_error: IdentityUniqueness.uniqueness_error("username"))
+          end
+
+          private
+
+          def fail_uniqueness_or_raise(error)
+            if IdentityUniqueness.uniqueness_taken?(error, :username)
+              context.fail!(application_error: IdentityUniqueness.uniqueness_error("username"))
+              return
+            end
+
+            raise error
+          end
+        end
+
+        class UpdateEmail < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :email, is_a: String, required: true
+
+          def call
+            normalized = email.to_s.strip
+            if user.email.to_s == normalized
+              context.user = user
+              context.changed = false
+              return
+            end
+
+            result = CommandTower::UserAttributes::Mutate.call(user:, email: normalized)
+            unless result.success?
+              details = result.invalid_argument_hash.transform_values { _1[:msg].to_s }
+              context.fail!(application_error: CommandTower::Errors::ValidationError.new(details:))
+              return
+            end
+
+            user.reload
+            user.update!(email_validated: false) if user.email_validated
+
+            context.user = user
+            context.changed = true
+          rescue ActiveRecord::RecordInvalid => error
+            fail_uniqueness_or_raise(error)
+          rescue ActiveRecord::RecordNotUnique
+            context.fail!(application_error: IdentityUniqueness.uniqueness_error("email"))
+          end
+
+          private
+
+          def fail_uniqueness_or_raise(error)
+            if IdentityUniqueness.uniqueness_taken?(error, :email)
+              context.fail!(application_error: IdentityUniqueness.uniqueness_error("email"))
+              return
+            end
+
+            raise error
+          end
+        end
+
+        class SetEmailValidated < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :email_validated, is_a: [TrueClass, FalseClass], required: true
+
+          def call
+            if user.email_validated == email_validated
+              context.user = user
+              context.changed = false
+              return
+            end
+
+            user.update!(email_validated:)
+            context.user = user
+            context.changed = true
+          end
+        end
+
+        class ListAssignableRoles < CommandTower::Services::ApplicationService
+          def call
+            context.roles = CommandTower::Authorization::AssignableRoles.catalog
+          end
+        end
+
+        class RoleAssignmentPolicy < CommandTower::Services::ApplicationService
+          validate :actor, is_a: User, required: true
+          validate :target, is_a: User, required: true
+          validate :desired_roles, is_a: Array, required: true
+
+          def call
+            desired = desired_roles.map(&:to_s)
+            assignable = CommandTower::Authorization::AssignableRoles.names
+
+            if desired.any? { |name| protected_role?(name) }
+              return context.fail!(application_error: CommandTower::Errors::ForbiddenError.new)
+            end
+
+            unknown = desired.reject { |name| assignable.include?(name) }
+            if unknown.any?
+              return context.fail!(
+                application_error: CommandTower::Errors::ValidationError.new(
+                  details: { roles: "unknown_or_unassignable" }
+                )
+              )
+            end
+
+            current = Array(target.roles).map(&:to_s)
+            current_assignable = current.select { |name| assignable.include?(name) }
+            newly_assigned = desired - current_assignable
+            actor_grants = CommandTower::Authorization::EffectiveEntityGrants.for_user(actor)
+
+            newly_assigned.each do |role_name|
+              candidate_grants = CommandTower::Authorization::EffectiveEntityGrants.for_role(role_name)
+              next if CommandTower::Authorization::EffectiveEntityGrants.subset?(candidate_grants, actor_grants)
+
+              return context.fail!(application_error: CommandTower::Errors::ForbiddenError.new)
+            end
+
+            preserved = current.reject { |name| assignable.include?(name) }
+            proposed = preserved + desired.uniq
+
+            if target.id == actor.id && self_lockout?(actor_grants, proposed)
+              return context.fail!(application_error: CommandTower::Errors::ForbiddenError.new)
+            end
+
+            context.desired_roles = desired.uniq
+          end
+
+          private
+
+          def protected_role?(name)
+            role = CommandTower::Authorization::Role.roles[name]
+            name.to_s == CommandTower::Authorization::AssignableRoles::OWNER_NAME ||
+              role&.allow_everything
+          end
+
+          def self_lockout?(before_grants, proposed_role_names)
+            grants = CommandTower::Authorization::EffectiveEntityGrants
+            after_grants = grants.for_role_names(proposed_role_names)
+
+            if grants.includes?(before_grants, "admin_rbac_assignments") &&
+                !grants.includes?(after_grants, "admin_rbac_assignments")
+              return true
+            end
+
+            grants.includes?(before_grants, "admin_workspace") &&
+              !grants.includes?(after_grants, "admin_workspace")
+          end
+        end
+
+        class ReplaceUserRoles < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :desired_roles, is_a: Array, required: true
+
+          def call
+            assignable = CommandTower::Authorization::AssignableRoles.names
+            desired = desired_roles.map(&:to_s).uniq
+            current = Array(user.roles).map(&:to_s)
+            current_assignable = current.select { |name| assignable.include?(name) }
+            preserved = current.reject { |name| assignable.include?(name) }
+            next_roles = (preserved + desired).uniq
+
+            assigned = desired - current_assignable
+            revoked = current_assignable - desired
+            changed = assigned.any? || revoked.any?
+
+            unless changed
+              context.user = user
+              context.assigned_roles = []
+              context.revoked_roles = []
+              context.changed = false
+              return
+            end
+
+            user.roles = next_roles
+            unless user.save
+              return context.fail!(
+                application_error: CommandTower::Errors::ValidationError.new(
+                  details: { roles: "could_not_save" }
+                )
+              )
+            end
+
+            context.user = user
+            context.assigned_roles = assigned
+            context.revoked_roles = revoked
+            context.changed = true
+          end
+        end
+      end
+    end
+  end
+end
+

data/app/services/command_tower/services/admin/workspace/manifest.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Admin
+      module Workspace
+        class Manifest < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            context.tools = authorized_definitions.map { |definition| project(definition) }
+          end
+
+          private
+
+          def authorized_definitions
+            CommandTower.config.registry.admin_workspace.definitions.values.select do |definition|
+              granted?(definition.required_entity)
+            end.sort_by { |definition| [definition.group, definition.sort_order, definition.id] }
+          end
+
+          def granted?(entity_name)
+            Array(user.roles).any? do |role_name|
+              role = CommandTower::Authorization::Role.roles[role_name]
+              next false unless role
+
+              role.allow_everything || role.entities.any? { |entity| entity.name.to_s == entity_name }
+            end
+          end
+
+          def project(definition)
+            base = {
+              id: definition.id,
+              label: definition.label,
+              description: definition.description,
+              route: definition.route,
+              group: definition.group,
+              sort_order: definition.sort_order,
+              icon: definition.icon
+            }
+            base.merge(
+              CommandTower::AdminScope::ManifestProjection.call(definition:, principal: user)
+            )
+          end
+        end
+      end
+    end
+  end
+end