plan_my_stuff 0.3.0 → 0.4.0

data/lib/plan_my_stuff/configuration.rb

@@ -2,6 +2,33 @@
 
 module PlanMyStuff
   class Configuration
+    # Default controller for each controllable route group. Consuming apps
+    # override by assigning values into +controllers+; lookups go through
+    # +controller_for+ which falls back to this table.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    DEFAULT_CONTROLLERS = {
+      'issues': 'plan_my_stuff/issues',
+      'comments': 'plan_my_stuff/comments',
+      'labels': 'plan_my_stuff/labels',
+      'projects': 'plan_my_stuff/projects',
+      'project_items': 'plan_my_stuff/project_items',
+      'testing_projects': 'plan_my_stuff/testing_projects',
+      'testing_project_items': 'plan_my_stuff/testing_project_items',
+      'issues/closures': 'plan_my_stuff/issues/closures',
+      'issues/viewers': 'plan_my_stuff/issues/viewers',
+      'issues/takes': 'plan_my_stuff/issues/takes',
+      'issues/waitings': 'plan_my_stuff/issues/waitings',
+      'issues/links': 'plan_my_stuff/issues/links',
+      'issues/approvals': 'plan_my_stuff/issues/approvals',
+      'project_items/statuses': 'plan_my_stuff/project_items/statuses',
+      'project_items/assignments': 'plan_my_stuff/project_items/assignments',
+      'testing_project_items/results': 'plan_my_stuff/testing_project_items/results',
+      'webhooks/github': 'plan_my_stuff/webhooks/github',
+      'webhooks/aws': 'plan_my_stuff/webhooks/aws',
+    }.freeze
+
     # @return [String] GitHub PAT with repo and project scopes. Required.
     attr_accessor :access_token
 
@@ -14,6 +41,12 @@ module PlanMyStuff
     # @return [Integer, nil] default GitHub Projects V2 number for add_to_project calls
     attr_accessor :default_project_number
 
+    # @return [Integer, nil] GitHub Projects V2 number of the template project to clone
+    # when creating new TestingProjects. When set, TestingProject.create! copies the
+    # template (preserving its fields and board layout) instead of bootstrapping fields
+    # from scratch. Leave nil to use the default bootstrap-fields path.
+    attr_accessor :testing_template_project_number
+
     # @return [String] consuming app's user model class name, constantized for lookups
     attr_accessor :user_class
 
@@ -61,14 +94,14 @@ module PlanMyStuff
     #
     attr_accessor :job_classes
 
-    # @return [Proc, nil] custom notifier for deferred requests, or nil to use DeferredMailer
-    attr_accessor :deferred_notifier
-
-    # @return [String, nil] sender address for built-in deferred request notifications
-    attr_accessor :deferred_email_from
-
-    # @return [String, nil] recipient address for built-in deferred request notifications
-    attr_accessor :deferred_email_to
+    # Fallback actor for notification events when a caller does not pass +user:+.
+    # Set to a proc/lambda that returns the current request user.
+    #
+    # Example: +config.current_user = -> { Current.user }+
+    #
+    # @return [Proc, nil]
+    #
+    attr_accessor :current_user
 
     # Shared field definitions stored in issue/comment metadata.
     # Keys are field names, values are hashes with :type and :required.
@@ -99,6 +132,13 @@ module PlanMyStuff
     #
     attr_accessor :project_custom_fields
 
+    # Testing-project-only field definitions, deep-merged on top of shared custom_fields.
+    # Context-specific config wins on key conflicts.
+    #
+    # @return [Hash{Symbol => Hash}]
+    #
+    attr_accessor :testing_custom_fields
+
     # @return [String, nil] URL prefix for building user-facing ticket URLs in the consuming app
     attr_accessor :issues_url_prefix
 
@@ -114,8 +154,14 @@ module PlanMyStuff
     # @return [String, nil] HMAC secret for GitHub webhook signature verification (required when webhooks mounted)
     attr_accessor :webhook_secret
 
-    # @return [String, nil] shared secret for AWS webhook signature verification (required when AWS webhook mounted)
-    attr_accessor :aws_webhook_secret
+    # @return [String, nil] expected SNS topic ARN for AWS webhook validation
+    attr_accessor :sns_topic_arn
+
+    # @return [String, nil] suffix matched against ECS event resource ARNs (e.g. 'rawr-production-2-web')
+    attr_accessor :aws_service_identifier
+
+    # @return [String, nil] commit hash of the deploying build, prefix-matched against issue metadata commit_sha
+    attr_accessor :production_commit_sha
 
     # Canonical status name to display alias map. Allows consuming apps to rename
     # pipeline statuses (e.g. "Submitted" to "Triaged").
@@ -130,6 +176,17 @@ module PlanMyStuff
     # @return [String] branch name that triggers deployment when a PR merges
     attr_accessor :production_branch
 
+    # Hash mapping consuming-app user id to GitHub login. Used by the
+    # "Take" UI flow to assign the GitHub user when a support user claims
+    # an issue. Keys are whatever +config.user_id_method+ returns on the
+    # current user.
+    #
+    # Example: +config.github_login_for = { 1 => 'some_username', 2 => 'octocat' }+
+    #
+    # @return [Hash{Object => String}]
+    #
+    attr_accessor :github_login_for
+
     # Per-group route mounting toggles. Keys: :webhooks, :issues, :projects.
     # Set a key to false to skip mounting that route group.
     #
@@ -137,6 +194,112 @@ module PlanMyStuff
     #
     attr_accessor :mount_groups
 
+    # Per-route controller overrides. Keys are the controllable route symbols
+    # defined in +DEFAULT_CONTROLLERS+; values are fully-qualified controller
+    # paths (e.g. +'my_app/issues'+). Unset keys fall back to the gem default.
+    # Consuming apps typically subclass the gem controller to add before_actions
+    # or tweak responses, then swap their subclass in here.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    attr_accessor :controllers
+
+    # Whether to use Rails.cache for ETag-based HTTP caching of GitHub reads.
+    # Defaults to true; set to false to bypass the cache entirely.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :cache_enabled
+
+    # Opaque app-supplied version string embedded in every PMS cache key.
+    # Bumping this string invalidates all cached entries from the consuming
+    # app's side (e.g. after a deploy or schema change). Defaults to nil.
+    #
+    # @return [String, nil]
+    #
+    attr_accessor :cache_version
+
+    # Whether the reminders sweep performs any work. Defaults to +true+.
+    # Set to +false+ in apps that don't want follow-up reminders or inactivity
+    # auto-close.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :reminders_enabled
+
+    # Days-since-waiting at which reminder events fire. Per-issue override
+    # via +metadata.reminder_days+.
+    #
+    # @return [Array<Integer>]
+    #
+    attr_accessor :reminder_days
+
+    # Days of inactivity after which the sweep auto-closes a waiting issue.
+    #
+    # @return [Integer]
+    #
+    attr_accessor :inactivity_close_days
+
+    # Label name used to flag issues waiting on an end-user reply.
+    #
+    # @return [String]
+    #
+    attr_accessor :waiting_on_user_label
+
+    # Label name used to flag issues waiting on pending approvals.
+    #
+    # @return [String]
+    #
+    attr_accessor :waiting_on_approval_label
+
+    # Label name applied to issues auto-closed by the inactivity sweep.
+    # Removed when an issue is auto-reopened via a user reply.
+    #
+    # @return [String]
+    #
+    attr_accessor :user_inactive_label
+
+    # Whether the archive sweep performs any work. Defaults to +true+.
+    # Set to +false+ in apps that don't want auto-archiving of aged-closed
+    # issues.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :archiving_enabled
+
+    # Days after +closed_at+ at which a non-inactive-closed issue becomes an
+    # archive candidate.
+    #
+    # @return [Integer]
+    #
+    attr_accessor :archive_closed_after_days
+
+    # Label name added to archived issues. Also used by the sweep as a
+    # skip marker to avoid re-archiving the same issue.
+    #
+    # @return [String]
+    #
+    attr_accessor :archived_label
+
+    # Whether to process incoming AWS webhook events. Defaults to +Rails.env.production?+.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :process_aws_webhooks
+
+    # Class instantiated per request for SNS signature verification.
+    # Must respond to +authenticate!(raw_body)+.
+    #
+    # @return [Class]
+    #
+    attr_accessor :sns_verifier_class
+
+    # Exception class rescued during SNS signature verification.
+    #
+    # @return [Class]
+    #
+    attr_accessor :sns_verifier_error
+
     # Named repo configs. Set via config.repos[:element] = 'BrandsInsurance/Element'.
     #
     # @return [Hash{Symbol => String}]
@@ -157,11 +320,30 @@ module PlanMyStuff
       @issue_custom_fields = {}
       @comment_custom_fields = {}
       @project_custom_fields = {}
+      @testing_custom_fields = {}
       @pipeline_enabled = true
       @pipeline_statuses = {}
       @main_branch = 'main'
       @production_branch = 'production'
       @mount_groups = { webhooks: true, issues: true, projects: true }
+      @controllers = {}
+      @cache_enabled = true
+      @github_login_for = {}
+      @reminders_enabled = true
+      @reminder_days = [1, 3, 7, 10, 14, 18].freeze
+      @inactivity_close_days = 30
+      @waiting_on_user_label = 'waiting-on-user'
+      @waiting_on_approval_label = 'waiting-on-approval'
+      @user_inactive_label = 'user-inactive'
+      @archiving_enabled = true
+      @archive_closed_after_days = 90
+      @archived_label = 'archived'
+      @process_aws_webhooks = Rails.env.production?
+      @sns_verifier_class = ::Aws::SNS::MessageVerifier if defined?(::Aws::SNS::MessageVerifier)
+      @sns_verifier_error =
+        if defined?(::Aws::SNS::MessageVerifier::VerificationError)
+          ::Aws::SNS::MessageVerifier::VerificationError
+        end
     end
 
     # Sets the authentication block for engine controllers.
@@ -208,11 +390,29 @@ module PlanMyStuff
         when :issue then issue_custom_fields
         when :comment then comment_custom_fields
         when :project then project_custom_fields
+        when :testing then testing_custom_fields
         else {}
         end
 
       custom_fields.deep_merge(context_fields)
     end
+
+    # Returns the controller path for the given route group, preferring a
+    # consuming-app override from +controllers+ and falling back to the gem
+    # default from +DEFAULT_CONTROLLERS+. The returned value always begins
+    # with +'/'+ so the isolated engine does not re-prefix it with
+    # +plan_my_stuff/+.
+    #
+    # @param key [Symbol]
+    #
+    # @raise [KeyError] if +key+ is not a controllable route group
+    #
+    # @return [String]
+    #
+    def controller_for(key)
+      path = controllers[key] || DEFAULT_CONTROLLERS.fetch(key)
+      path.start_with?('/') ? path : "/#{path}"
+    end
   end
 
   class ConfigurationError < StandardError

data/lib/plan_my_stuff/custom_fields.rb

@@ -60,28 +60,42 @@ module PlanMyStuff
       to_h.to_json(...)
     end
 
-    private
-
-      def respond_to_missing?(method_name, include_private = false)
-        key = method_name.to_s.delete_suffix('=').to_sym
-        @schema.key?(key) || @data.key?(key) || super
-      end
+    # @param method_name [Symbol]
+    # @param include_private [Boolean]
+    #
+    # @return [Boolean]
+    #
+    def respond_to_missing?(method_name, include_private = false)
+      key = method_name.to_s.delete_suffix('=').to_sym
+      @schema.key?(key) || @data.key?(key) || super
+    end
 
-      def method_missing(method_name, *args)
-        name = method_name.to_s
+    # Dynamic reader/writer access to custom field values. Only resolves field
+    # names that appear in the schema or already have a value in @data; unknown
+    # names fall through to super (raising NoMethodError).
+    #
+    # @param method_name [Symbol]
+    # @param args [Array]
+    #
+    # @return [Object]
+    #
+    def method_missing(method_name, *args)
+      name = method_name.to_s
 
-        if name.end_with?('=')
-          key = name.delete_suffix('=').to_sym
-          if @schema.key?(key) || @data.key?(key)
-            return @data[key] = args.first
-          end
-        elsif @schema.key?(method_name) || @data.key?(method_name)
-          return @data[method_name]
+      if name.end_with?('=')
+        key = name.delete_suffix('=').to_sym
+        if @schema.key?(key) || @data.key?(key)
+          return @data[key] = args.first
         end
-
-        super
+      elsif @schema.key?(method_name) || @data.key?(method_name)
+        return @data[method_name]
       end
 
+      super
+    end
+
+    private
+
       # @return [void]
       def validate_custom_fields
         validate_unknown_fields

data/lib/plan_my_stuff/engine.rb

@@ -3,9 +3,5 @@
 module PlanMyStuff
   class Engine < ::Rails::Engine
     isolate_namespace PlanMyStuff
-
-    rake_tasks do
-      load(File.expand_path('../tasks/plan_my_stuff.rake', __dir__))
-    end
   end
 end

data/lib/plan_my_stuff/errors.rb

@@ -66,6 +66,17 @@ module PlanMyStuff
     end
   end
 
+  # Raised when a webhook HMAC-SHA256 signature check fails
+  class WebhookSignatureError < Error
+    def initialize(message = 'Invalid webhook signature')
+      super
+    end
+  end
+
+  # Raised when a pipeline operation fails
+  class PipelineError < Error
+  end
+
   # Raised when custom field validation fails (Phase 1)
   class ValidationError < Error
     # @return [String, nil]
@@ -84,4 +95,42 @@ module PlanMyStuff
       super(message)
     end
   end
+
+  # Raised when a caller is not authorized to perform an action (e.g.
+  # a non-support user attempts to manage approvers on an issue).
+  class AuthorizationError < Error
+  end
+
+  # Raised when an operation is attempted on an issue whose conversation
+  # is locked on GitHub (archived or manually locked).
+  class LockedIssueError < Error
+  end
+
+  # Raised by +PlanMyStuff::Pipeline+ forward transitions when the linked
+  # +Issue+ has any pending manager approvals.
+  class PendingApprovalsError < ValidationError
+    # @return [PlanMyStuff::Issue, nil]
+    attr_reader :issue
+
+    # @return [Integer]
+    attr_reader :pending_count
+
+    # @param message [String, nil]
+    # @param issue [PlanMyStuff::Issue, nil]
+    # @param pending_count [Integer]
+    #
+    def initialize(message = nil, issue: nil, pending_count: 0)
+      @issue = issue
+      @pending_count = pending_count
+      super(message || default_message)
+    end
+
+    private
+
+      # @return [String]
+      def default_message
+        "Issue ##{issue&.number} has #{pending_count} pending approval(s); " \
+          'cannot move forward through pipeline.'
+      end
+  end
 end