plan_my_stuff 0.6.0 → 0.8.0

data/app/views/plan_my_stuff/testing_projects/partials/items/_form.html.erb

@@ -1,3 +1,4 @@
+<%# locals: (project:) %>
 <%= form_with(url: plan_my_stuff.testing_project_items_path(project.number), method: :post, local: true) do |form| %>
   <div>
     <%= form.label(:title, 'Title') %>

data/app/views/plan_my_stuff/testing_projects/show.html.erb

@@ -7,7 +7,7 @@
   <% end %>
 </p>
 
-<% if @support_user && @project.metadata.subject_urls.any? %>
+<% if @support_user && @project.metadata.subject_urls.present? %>
   <p>
     <strong>Subject URLs:</strong>
     <% @project.metadata.subject_urls.each do |url| %>
@@ -20,7 +20,7 @@
   <p><strong>Due:</strong> <%= @project.metadata.due_date %></p>
 <% end %>
 
-<% if @statuses.any? %>
+<% if @statuses.present? %>
   <table>
     <thead>
       <tr>

data/config/routes.rb

@@ -12,7 +12,7 @@ PlanMyStuff::Engine.routes.draw do
       if config.pipeline_enabled
         resource(
           :take,
-          only: :create,
+          only: %i[create destroy],
           controller: config.controller_for(:'issues/takes'),
         )
       end
@@ -32,7 +32,7 @@ PlanMyStuff::Engine.routes.draw do
 
   if mount_groups.fetch(:projects, true)
     resources :projects, except: %i[destroy], controller: config.controller_for(:projects) do
-      resources :items, only: %i[create], controller: config.controller_for(:project_items) do
+      resources :items, only: %i[create destroy], controller: config.controller_for(:project_items) do
         resource :status, only: %i[update], controller: config.controller_for(:'project_items/statuses')
         resource :assignment, only: %i[update destroy], controller: config.controller_for(:'project_items/assignments')
       end

data/lib/generators/plan_my_stuff/install/templates/initializer.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
-PMS.configure do |config|
+PlanMyStuff.configure do |config|
   # --------------------------------------------------------------------------
   # Authentication (required)
   # --------------------------------------------------------------------------
   # GitHub PAT with `repo` and `project` scopes. All API calls use this token.
   config.access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_token)
 
+  # Classic PAT (requires `repo` scope) for the Issues Import API (golden-comet-preview).
+  # Fine-grained tokens are not supported by that endpoint.
+  # config.import_access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_import_token)
+
   # --------------------------------------------------------------------------
   # Organization (required)
   # --------------------------------------------------------------------------
@@ -93,8 +97,13 @@ PMS.configure do |config|
   # --------------------------------------------------------------------------
   # URL prefix
   # --------------------------------------------------------------------------
-  # Prefix for building user-facing ticket URLs in your app.
-  # config.issues_url_prefix = 'https://myapp.example.com/tickets/'
+  # Prefix for building user-facing ticket URLs in your app. The issue
+  # number is appended to form `Issue#user_link`, which the gem also
+  # writes as the visible body of the GitHub issue.
+  # Recommended default:
+  #   url_options = Rails.application.config.action_mailer.default_url_options
+  #   config.issues_url_prefix =
+  #     "#{url_options[:protocol] || 'http'}://#{url_options[:host]}/issues"
 
   # --------------------------------------------------------------------------
   # Request gateway
@@ -114,6 +123,18 @@ PMS.configure do |config|
   # does not pass an explicit user: kwarg. Proc/lambda called at event time.
   # config.current_user = -> { Current.user }
 
+  # --------------------------------------------------------------------------
+  # Controller rescue hook
+  # --------------------------------------------------------------------------
+  # Invoked from every gem controller rescue block, after the gem logs the
+  # error class/message and stack trace via Rails.logger.error and just
+  # before the user-facing flash + redirect/render. Forwards the rescued
+  # exception so consuming apps can fire monitoring even though the rescue
+  # swallows the error. Receives the rescued exception; return value is
+  # ignored. Defaults to nil (no-op).
+  #
+  # config.controller_rescue = ->(error) { MonitoringService.notice_error(error) }
+
   # --------------------------------------------------------------------------
   # Custom fields
   # --------------------------------------------------------------------------
@@ -142,6 +163,22 @@ PMS.configure do |config|
   # Testing-project-only fields (merged on top of shared, context wins on conflicts):
   # config.testing_custom_fields = {}
 
+  # --------------------------------------------------------------------------
+  # Issue types (org-side renames)
+  # --------------------------------------------------------------------------
+  # The gem speaks in canonical type names: 'Bug', 'Feature',
+  # 'IT Issue / Hardware', 'Other', 'Performance', 'Question', 'Task'.
+  # Symbol shortcuts (`:bug`, `:feature`, `:it_issue`, `:other`, `:performance`,
+  # `:question`, `:task`) resolve to those canonical names automatically.
+  # If your GitHub org uses different names for any of them, map the
+  # canonical name to your org's name here and PMS will translate on
+  # write. Missing keys pass through unchanged.
+  #
+  # config.issue_types = {
+  #   'Bug' => 'User Bug',
+  #   'Feature' => 'Enhancement',
+  # }
+
   # --------------------------------------------------------------------------
   # Release pipeline
   # --------------------------------------------------------------------------
@@ -157,6 +194,22 @@ PMS.configure do |config|
   #   'Completed' => 'Done',
   # }
 
+  # Display name for the Testing single-select field on the pipeline project.
+  # config.pipeline_testing_field_name = 'Testing'
+
+  # Display labels for the canonical Testing field option keys.
+  # config.pipeline_testing_values = {
+  #   active: 'Testing',
+  #   inactive: 'Not testing',
+  # }
+
+  # Whether the pipeline sweep removes aged-out Completed items.
+  # config.pipeline_completion_purge_enabled = true
+
+  # Hours after a project item's last update at which the sweep removes it
+  # from the pipeline if its status is Completed.
+  # config.pipeline_completion_ttl_hours = 24
+
   # config.main_branch = 'main'
   # config.production_branch = 'production'
 

data/lib/plan_my_stuff/approval.rb

@@ -5,14 +5,14 @@ require 'active_model'
 module PlanMyStuff
   # Value object representing a single manager approval on an +Issue+.
   # Persisted in +IssueMetadata#approvals+ and returned from
-  # +Issue.request_approvals!+, +Issue.approve!+, and
+  # +Issue.request_approvals!+, +Issue.approve!+, +Issue.reject!+, and
   # +Issue.revoke_approval!+.
   #
   # Mirrors +PlanMyStuff::Link+: +ActiveModel::Attributes+-backed, with
   # +Serializers::JSON+ for round-trip through the metadata blob.
   #
   class Approval
-    STATUSES = %w[pending approved].freeze
+    STATUSES = %w[pending approved rejected].freeze
 
     include ActiveModel::Model
     include ActiveModel::Attributes
@@ -20,10 +20,12 @@ module PlanMyStuff
 
     # @return [Integer] app-side user id of the required approver
     attribute :user_id, :integer
-    # @return [String] +"pending"+ or +"approved"+
+    # @return [String] +"pending"+, +"approved"+, or +"rejected"+
     attribute :status, :string, default: 'pending'
     # @return [DateTime, nil] timestamp when status flipped to +"approved"+
     attribute :approved_at, :datetime
+    # @return [DateTime, nil] timestamp when status flipped to +"rejected"+
+    attribute :rejected_at, :datetime
 
     validates :user_id, presence: true, numericality: { greater_than: 0, only_integer: true }
     validates :status, inclusion: { in: STATUSES }
@@ -38,6 +40,11 @@ module PlanMyStuff
       status == 'approved'
     end
 
+    # @return [Boolean]
+    def rejected?
+      status == 'rejected'
+    end
+
     # Lazy-resolves the app-side user for this approval.
     # Not memoized -- +PlanMyStuff::UserResolver+ owns caching.
     #
@@ -52,7 +59,8 @@ module PlanMyStuff
       {
         user_id: user_id,
         status: status,
-        approved_at: approved_at&.iso8601,
+        approved_at: PlanMyStuff.format_time(approved_at),
+        rejected_at: PlanMyStuff.format_time(rejected_at),
       }
     end
 

data/lib/plan_my_stuff/aws_sns_simulator.rb

@@ -27,15 +27,21 @@ module PlanMyStuff
     # +production_commit_sha+ from +PlanMyStuff.configuration+ (this
     # task is dev-only, so there's no reason to parameterize them).
     #
+    # @raise [PlanMyStuff::ConfigurationError] if sns details are missing
+    #
     # @param endpoint_url [String] full URL including path
     # @param event_name [String] ECS eventName (default completed)
     #
     # @return [Net::HTTPResponse]
     #
-    def post(endpoint_url:, event_name: DEFAULT_EVENT)
+    def post!(endpoint_url:, event_name: DEFAULT_EVENT)
       config = PlanMyStuff.configuration
-      raise('PlanMyStuff.configuration.sns_topic_arn is blank') if config.sns_topic_arn.blank?
-      raise('PlanMyStuff.configuration.aws_service_identifier is blank') if config.aws_service_identifier.blank?
+      if config.sns_topic_arn.blank?
+        raise(PlanMyStuff::ConfigurationError, 'PlanMyStuff.configuration.sns_topic_arn is blank')
+      end
+      if config.aws_service_identifier.blank?
+        raise(PlanMyStuff::ConfigurationError, 'PlanMyStuff.configuration.aws_service_identifier is blank')
+      end
 
       topic_arn = config.sns_topic_arn
       service_arn = "arn:aws:ecs:us-east-1:000000000000:service/simulated-cluster/#{config.aws_service_identifier}"
@@ -73,7 +79,7 @@ module PlanMyStuff
         'eventType' => 'INFO',
         'eventName' => event_name,
         'deploymentId' => "ecs-svc/#{SecureRandom.hex(8)}",
-        'updatedAt' => Time.now.utc.iso8601,
+        'updatedAt' => PlanMyStuff.format_time(Time.now.utc),
       }
       detail['commitSha'] = commit_sha if commit_sha
 
@@ -83,7 +89,7 @@ module PlanMyStuff
         'detail-type' => 'ECS Deployment State Change',
         'source' => 'aws.ecs',
         'account' => '000000000000',
-        'time' => Time.now.utc.iso8601,
+        'time' => PlanMyStuff.format_time(Time.now.utc),
         'region' => 'us-east-1',
         'resources' => [service_arn],
         'detail' => detail,
@@ -92,7 +98,7 @@ module PlanMyStuff
 
     # @return [Hash]
     def build_sns_envelope(message:, topic_arn:)
-      now = Time.now.utc.iso8601
+      now = PlanMyStuff.format_time(Time.now.utc)
       {
         'Type' => 'Notification',
         'MessageId' => SecureRandom.uuid,

data/lib/plan_my_stuff/base_metadata.rb

@@ -40,7 +40,7 @@ module PlanMyStuff
           metadata.app_name = hash[:app_name]
           metadata.created_by = hash[:created_by]
           metadata.visibility = hash.fetch(:visibility, 'internal')
-          metadata.custom_fields = CustomFields.new(
+          metadata.custom_fields = PlanMyStuff::CustomFields.new(
             custom_fields_schema,
             hash[:custom_fields] || {},
           )
@@ -69,10 +69,10 @@ module PlanMyStuff
           metadata.gem_version = PlanMyStuff::VERSION::STRING
           metadata.rails_env = (defined?(Rails) && Rails.respond_to?(:env)) ? Rails.env.to_s : nil
           metadata.app_name = config.app_name
-          resolved = UserResolver.resolve(user)
-          metadata.created_by = resolved.present? ? UserResolver.user_id(resolved) : nil
+          resolved = PlanMyStuff::UserResolver.resolve(user)
+          metadata.created_by = resolved.present? ? PlanMyStuff::UserResolver.user_id(resolved) : nil
           metadata.visibility = visibility
-          metadata.custom_fields = CustomFields.new(
+          metadata.custom_fields = PlanMyStuff::CustomFields.new(
             custom_fields_schema,
             custom_fields_data,
           )
@@ -119,8 +119,6 @@ module PlanMyStuff
 
     # Validates custom fields against the schema.
     #
-    # @raise [ActiveModel::ValidationError] if validation fails
-    #
     # @return [true]
     #
     def validate_custom_fields!
@@ -131,14 +129,5 @@ module PlanMyStuff
     def to_json(...)
       to_h.to_json(...)
     end
-
-    private
-
-      # @return [String, nil]
-      def format_time(time)
-        return if time.nil?
-
-        time.utc.iso8601
-      end
   end
 end

data/lib/plan_my_stuff/base_project.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  # Shared base for GitHub Projects V2 wrappers. Holds attribute definitions,
-  # generic find/list/update machinery, hydration, and instance helpers.
-  # Concrete subclasses (Project, TestingProject) add their own +create!+
-  # behavior and optional filtering on +find+/+list+.
+  # Shared base for GitHub Projects V2 wrappers. Holds attribute definitions, generic find/list/update machinery,
+  # hydration, and instance helpers. Concrete subclasses (Project, TestingProject) add their own +create!+ behavior
+  # and optional filtering on +find+/+list+.
   #
-  # Not instantiated directly. +find+ and +list+ dispatch via +build_detail+/
-  # +build_summary+ to the correct concrete subclass based on the metadata
-  # +kind+ field in the project readme.
+  # Not instantiated directly. +find+ and +list+ dispatch via +build_detail+/+build_summary+ to the correct concrete
+  # subclass based on the metadata +kind+ field in the project readme.
   class BaseProject < PlanMyStuff::ApplicationRecord
     MAX_AUTO_PAGINATE_ITEMS = 500
     ITEMS_PER_PAGE = 100
@@ -45,9 +43,10 @@ module PlanMyStuff
     attribute :has_next_page
 
     class << self
-      # Generic find - returns whichever concrete project type is at the given
-      # number, dispatching on metadata kind. Subclasses may override to apply
-      # filtering (e.g. Project raises for testing projects by default).
+      # Generic find - returns whichever concrete project type is at the given number, dispatching on metadata kind.
+      # Subclasses may override to apply filtering (e.g. Project raises for testing projects by default).
+      #
+      # @raise [ArgumentError] if paginate mode is invalid
       #
       # @param number [Integer]
       # @param paginate [Symbol] :auto (default) or :cursor
@@ -68,9 +67,8 @@ module PlanMyStuff
         end
       end
 
-      # Generic list - returns all projects in the configured organization,
-      # each dispatched to its concrete type (Project or TestingProject).
-      # Subclasses may override to apply filtering.
+      # Generic list - returns all projects in the configured organization, each dispatched to its concrete type
+      # (Project or TestingProject). Subclasses may override to apply filtering.
       #
       # @return [Array<PlanMyStuff::BaseProject>]
       #
@@ -124,7 +122,7 @@ module PlanMyStuff
           end
 
           body = readme.nil? ? parsed[:body] : readme
-          update_input[:readme] = PlanMyStuff::MetadataParser.serialize(existing_metadata, body)
+          update_input[:readme] = PlanMyStuff::MetadataParser.serialize!(existing_metadata, body)
         end
 
         PlanMyStuff.client.graphql(
@@ -135,10 +133,9 @@ module PlanMyStuff
         find(project_number)
       end
 
-      # Clones an existing GitHub Project into the configured organization.
-      # The copy inherits all custom fields and board layout from the source.
-      # Returns the newly created project via +find+, dispatched to the correct
-      # concrete subclass (Project or TestingProject) based on the cloned readme.
+      # Clones an existing GitHub Project into the configured organization. The copy inherits all custom fields and
+      # board layout from the source. Returns the newly created project via +find+, dispatched to the correct concrete
+      # subclass (Project or TestingProject) based on the cloned readme.
       #
       # @param source_number [Integer] project number of the project to copy from
       # @param title [String] title for the new project
@@ -168,11 +165,13 @@ module PlanMyStuff
 
       # Resolves a project number, falling back to config.default_project_number.
       #
+      # @raise [ArgumentError] if project_number is nil and config.default_project_number is not set
+      #
       # @param project_number [Integer, nil]
       #
       # @return [Integer]
       #
-      def resolve_default_project_number(project_number)
+      def resolve_default_project_number!(project_number)
         return project_number if project_number.present?
 
         PlanMyStuff.configuration.default_project_number ||
@@ -181,8 +180,8 @@ module PlanMyStuff
 
       private
 
-        # Builds a summary Project from a list query node.
-        # Dispatches to TestingProject when the readme metadata has kind: "testing".
+        # Builds a summary Project from a list query node. Dispatches to TestingProject when the readme metadata has
+        # kind: "testing".
         #
         # @param node [Hash]
         #
@@ -193,12 +192,12 @@ module PlanMyStuff
           parsed_meta = PlanMyStuff::MetadataParser.parse(raw_readme)
           klass = dispatch_project_class(parsed_meta[:metadata])
           project = klass.new
-          project.__send__(:hydrate_summary, node)
+          project.__send__(:hydrate_summary, node, raw_readme: raw_readme, parsed_meta: parsed_meta)
           project
         end
 
-        # Builds a detailed Project from a find query response.
-        # Dispatches to TestingProject when the readme metadata has kind: "testing".
+        # Builds a detailed Project from a find query response. Dispatches to TestingProject when the readme metadata
+        # has kind: "testing".
         #
         # @param graphql_project [Hash]
         # @param items [Array<Hash>]
@@ -222,8 +221,8 @@ module PlanMyStuff
           project
         end
 
-        # Returns the appropriate project class based on the metadata kind field.
-        # Always dispatches to a concrete subclass (never BaseProject itself).
+        # Returns the appropriate project class based on the metadata kind field. Always dispatches to a concrete
+        # subclass (never BaseProject itself).
         #
         # @param meta_hash [Hash]
         #
@@ -280,8 +279,8 @@ module PlanMyStuff
           )
         end
 
-        # Fetches a single page of project data. Returns a lightweight hash
-        # for pagination loop consumption (not a Project instance).
+        # Fetches a single page of project data. Returns a lightweight hash for pagination loop consumption (not a
+        # Project instance).
         #
         # @param org [String]
         # @param number [Integer]
@@ -328,7 +327,7 @@ module PlanMyStuff
             number: content[:number],
             url: content[:url],
             state: content[:state],
-            repo: repo_name.present? ? PlanMyStuff::Repo.resolve(repo_name) : nil,
+            repo: repo_name.present? ? PlanMyStuff::Repo.resolve!(repo_name) : nil,
             status: extract_item_status(field_values),
             field_values: parse_field_values(field_values),
             updated_at: item[:updatedAt],
@@ -405,14 +404,24 @@ module PlanMyStuff
     #
     # @return [Hash] with :id and :options keys
     #
+    def status_field
+      status_field!
+    rescue
+      nil
+    end
+
+    # Returns the Status single-select field definition.
+    #
     # @raise [PlanMyStuff::APIError] if no Status field exists
     #
-    def status_field
-      field = fields.find { |f| f[:name] == 'Status' && f[:options] }
+    # @return [Hash] with :id and :options keys
+    #
+    def status_field!
+      status_field = fields.find { |f| f[:name] == 'Status' && f[:options] }
 
-      raise(APIError, "No 'Status' field found on project ##{number}") unless field
+      raise(PlanMyStuff::APIError, "No 'Status' field found on project ##{number}") if status_field.nil?
 
-      field
+      status_field
     end
 
     # @return [Boolean]
@@ -422,8 +431,6 @@ module PlanMyStuff
 
     # Persists the project. Creates if new, updates if persisted.
     #
-    # @raise [PlanMyStuff::StaleObjectError] on update if stale
-    #
     # @return [self]
     #
     def save!
@@ -447,13 +454,11 @@ module PlanMyStuff
       self
     end
 
-    # Updates this project on GitHub. Raises StaleObjectError if the remote
-    # has been modified since this instance was loaded.
+    # Updates this project on GitHub. Raises StaleObjectError if the remote has been modified since this instance was
+    # loaded.
     #
     # @param attrs [Hash] attributes to update (title:, readme:, description:, metadata:)
     #
-    # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
-    #
     # @return [self]
     #
     def update!(**attrs)
@@ -479,9 +484,8 @@ module PlanMyStuff
 
     private
 
-      # Kwargs derived from +metadata+ for forwarding to +self.class.create!+
-      # so +save!+ preserves in-memory metadata mutations on new records.
-      # Subclasses override to include type-specific metadata attributes.
+      # Kwargs derived from +metadata+ for forwarding to +self.class.create!+ so +save!+ preserves in-memory metadata
+      # mutations on new records. Subclasses override to include type-specific metadata attributes.
       #
       # @return [Hash]
       #
@@ -493,9 +497,8 @@ module PlanMyStuff
         }
       end
 
-      # Metadata hash forwarded to the class +update!+ so +save!+ preserves
-      # in-memory metadata mutations on persisted records. Returns +nil+ when
-      # the instance has no PMS metadata to avoid clobbering remote values.
+      # Metadata hash forwarded to the class +update!+ so +save!+ preserves in-memory metadata mutations on persisted
+      # records. Returns +nil+ when the instance has no PMS metadata to avoid clobbering remote values.
       #
       # @return [Hash, nil]
       #
@@ -511,7 +514,7 @@ module PlanMyStuff
       #
       # @return [void]
       #
-      def hydrate_summary(node)
+      def hydrate_summary(node, raw_readme:, parsed_meta:)
         @github_response = node
         self.id = node[:id]
         self.number = node[:number]
@@ -520,6 +523,9 @@ module PlanMyStuff
         self.url = node[:url]
         self.closed = node[:closed]
         self.updated_at = parse_github_time(node[:updatedAt])
+        self.raw_readme = raw_readme
+        self.metadata = build_project_metadata(parsed_meta[:metadata])
+        self.readme = parsed_meta[:body]
         persisted!
       end
 
@@ -553,6 +559,9 @@ module PlanMyStuff
         self.items = items.map { |item_hash| item_class.build(item_hash, project: self) }
         self.next_cursor = next_cursor
         self.has_next_page = has_next_page
+
+        status_field!
+
         persisted!
       end
 
@@ -579,11 +588,13 @@ module PlanMyStuff
         self.items = other.items
         self.next_cursor = other.next_cursor
         self.has_next_page = other.has_next_page
+
+        status_field!
+
         persisted!
       end
 
-      # Raises StaleObjectError if the remote project has been modified
-      # since this instance was loaded.
+      # Raises StaleObjectError if the remote project has been modified since this instance was loaded.
       #
       # @raise [PlanMyStuff::StaleObjectError]
       #
@@ -607,8 +618,8 @@ module PlanMyStuff
         ))
       end
 
-      # Builds the appropriate metadata object for this project instance.
-      # Dispatches to TestingProjectMetadata when kind is "testing".
+      # Builds the appropriate metadata object for this project instance. Dispatches to TestingProjectMetadata when
+      # kind is "testing".
       #
       # @param meta_hash [Hash]
       #
@@ -629,11 +640,11 @@ module PlanMyStuff
       # @return [Array<Hash>]
       #
       def extract_statuses(fields_nodes)
-        status_field = fields_nodes.find { |f| f[:name] == 'Status' && f.key?(:options) }
+        field = fields_nodes.find { |f| f[:name] == 'Status' && f.key?(:options) }
 
-        return [] unless status_field
+        return [] unless field
 
-        (status_field[:options] || []).map do |opt|
+        (field[:options] || []).map do |opt|
           { id: opt[:id], name: opt[:name] }
         end
       end
@@ -650,8 +661,10 @@ module PlanMyStuff
         end
       end
 
-      # Returns the item class used to build items for this project type.
-      # Subclasses override to return a domain-specific item class.
+      # Returns the item class used to build items for this project type. Subclasses override to return a
+      # domain-specific item class.
+      #
+      # @raise [NotImplementedError] if not implemented in subclass
       #
       # @return [Class]
       #