plan_my_stuff 0.1.1 → 0.3.0

data/lib/plan_my_stuff/base_metadata.rb

@@ -15,10 +15,6 @@ module PlanMyStuff
     attr_accessor :rails_env
     # @return [String, nil] consuming app name from config
     attr_accessor :app_name
-    # @return [Time, nil] timestamp of creation
-    attr_accessor :created_at
-    # @return [Time, nil] timestamp of last update
-    attr_accessor :updated_at
     # @return [Integer, nil] consuming app's user ID of the creator
     attr_accessor :created_by
     # @return [String] "public" or "internal"
@@ -33,20 +29,19 @@ module PlanMyStuff
         #
         # @param metadata [BaseMetadata]
         # @param hash [Hash]
+        # @param custom_fields_schema [Hash{Symbol => Hash}] merged schema for this context
         #
         # @return [void]
         #
-        def apply_common_from_hash(metadata, hash)
+        def apply_common_from_hash(metadata, hash, custom_fields_schema)
           metadata.schema_version = hash[:schema_version]
           metadata.gem_version = hash[:gem_version]
           metadata.rails_env = hash[:rails_env]
           metadata.app_name = hash[:app_name]
-          metadata.created_at = parse_time(hash[:created_at])
-          metadata.updated_at = parse_time(hash[:updated_at])
           metadata.created_by = hash[:created_by]
           metadata.visibility = hash.fetch(:visibility, 'internal')
           metadata.custom_fields = CustomFields.new(
-            PlanMyStuff.configuration.custom_fields,
+            custom_fields_schema,
             hash[:custom_fields] || {},
           )
         end
@@ -57,24 +52,28 @@ module PlanMyStuff
         # @param user [Object, Integer] user object or user_id
         # @param visibility [String] "public" or "internal"
         # @param custom_fields_data [Hash]
+        # @param custom_fields_schema [Hash{Symbol => Hash}] merged schema for this context
         #
         # @return [void]
         #
-        def apply_common_build(metadata, user:, visibility: 'internal', custom_fields_data: {})
+        def apply_common_build(
+          metadata,
+          user:,
+          visibility: 'internal',
+          custom_fields_data: {},
+          custom_fields_schema: {}
+        )
           config = PlanMyStuff.configuration
-          now = Time.now.utc
 
           metadata.schema_version = self::SCHEMA_VERSION
           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
-          metadata.created_at = now
-          metadata.updated_at = now
           resolved = UserResolver.resolve(user)
           metadata.created_by = resolved.present? ? UserResolver.user_id(resolved) : nil
           metadata.visibility = visibility
           metadata.custom_fields = CustomFields.new(
-            config.custom_fields,
+            custom_fields_schema,
             custom_fields_data,
           )
         end
@@ -92,6 +91,7 @@ module PlanMyStuff
 
     def initialize
       @visibility = 'internal'
+      @custom_fields = {}
     end
 
     # @return [Hash]
@@ -101,8 +101,6 @@ module PlanMyStuff
         gem_version: gem_version,
         rails_env: rails_env,
         app_name: app_name,
-        created_at: format_time(created_at),
-        updated_at: format_time(updated_at),
         created_by: created_by,
         visibility: visibility,
         custom_fields: custom_fields.to_h,
@@ -119,6 +117,16 @@ module PlanMyStuff
       visibility == 'public'
     end
 
+    # Validates custom fields against the schema.
+    #
+    # @raise [ActiveModel::ValidationError] if validation fails
+    #
+    # @return [true]
+    #
+    def validate_custom_fields!
+      custom_fields.validate! if custom_fields.is_a?(PlanMyStuff::CustomFields)
+    end
+
     # @return [String]
     def to_json(...)
       to_h.to_json(...)

data/lib/plan_my_stuff/client.rb

@@ -70,34 +70,14 @@ module PlanMyStuff
 
     # Resolves a repo param to a full "Org/Repo" string.
     #
-    # @param repo [Symbol, String, nil] repo key, full string, or nil for default
+    # @param repo [Symbol, String, PlanMyStuff::Repo, nil] repo key, full string, Repo instance, or nil for default
     #
     # @return [String] full repo path (e.g. "BrandsInsurance/Element")
     #
     # @raise [ArgumentError] if repo cannot be resolved
     #
     def resolve_repo(repo = nil)
-      repo ||= PlanMyStuff.configuration.default_repo
-
-      if repo.nil?
-        raise(
-          PlanMyStuff::ConfigurationError,
-          'No repo provided and config.default_repo is not set. ' \
-            'Either pass repo: explicitly or set config.default_repo in your initializer.',
-        )
-      end
-
-      case repo
-      when Symbol
-        resolved = PlanMyStuff.configuration.repos[repo]
-        raise(ArgumentError, "Unknown repo key: #{repo.inspect}") if resolved.nil?
-
-        resolved
-      when String
-        repo
-      else
-        raise(ArgumentError, "Cannot resolve repo: #{repo.inspect}")
-      end
+      PlanMyStuff::Repo.resolve(repo).full_name
     end
 
     private

data/lib/plan_my_stuff/comment.rb

@@ -20,6 +20,8 @@ module PlanMyStuff
     attr_accessor :body
     # @return [PlanMyStuff::Issue] parent issue
     attr_accessor :issue
+    # @return [Time, nil] GitHub's updated_at timestamp
+    attr_reader :updated_at
     # @param value [Symbol, String, nil]
     attr_writer :visibility
 
@@ -52,6 +54,7 @@ module PlanMyStuff
           custom_fields: custom_fields,
           issue_body: issue_body,
         )
+        comment_metadata.validate_custom_fields!
 
         header = build_header(resolved_user)
         full_body = "#{header}\n\n#{body}"
@@ -217,12 +220,12 @@ module PlanMyStuff
       raise_if_stale!
 
       new_body = attrs[:body] || body
+      new_body = preserve_header(new_body) if attrs.key?(:body)
       meta_hash = metadata.to_h
 
       if attrs.key?(:visibility)
         new_visibility = attrs[:visibility].to_s
         meta_hash[:visibility] = new_visibility
-        meta_hash[:updated_at] = Time.now.utc.iso8601
       end
 
       serialized = MetadataParser.serialize(meta_hash, new_body)
@@ -293,6 +296,19 @@ module PlanMyStuff
 
     private
 
+      # Prepends the existing header to new_body if the comment currently has one.
+      #
+      # @param new_body [String]
+      #
+      # @return [String]
+      #
+      def preserve_header(new_body)
+        existing_header = header
+        return new_body if existing_header.blank?
+
+        "#{existing_header}\n\n#{new_body}"
+      end
+
       # Populates this instance from a GitHub API response.
       #
       # @param github_comment [Object] Octokit comment response
@@ -303,6 +319,7 @@ module PlanMyStuff
       def hydrate_from_github(github_comment, issue:)
         @id = read_field(github_comment, :id)
         @raw_body = read_field(github_comment, :body)
+        @updated_at = parse_github_time(safe_read_field(github_comment, :updated_at))
         @issue = issue
 
         parsed = MetadataParser.parse(@raw_body)
@@ -322,6 +339,7 @@ module PlanMyStuff
         @id = other.id
         @body = other.body
         @raw_body = other.raw_body
+        @updated_at = other.updated_at
         @issue = other.issue
         @metadata = other.metadata
         @visibility = other.visibility
@@ -337,15 +355,11 @@ module PlanMyStuff
       #
       def raise_if_stale!
         return if new_record?
-        return if metadata.updated_at.nil?
+        return if updated_at.nil?
 
         github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
-        parsed = MetadataParser.parse(
-          github_comment.respond_to?(:body) ? github_comment.body : github_comment[:body],
-        )
-        remote_metadata = CommentMetadata.from_hash(parsed[:metadata])
-        remote_time = remote_metadata.updated_at
-        local_time = metadata.updated_at
+        remote_time = parse_github_time(safe_read_field(github_comment, :updated_at))
+        local_time = updated_at
 
         return if remote_time.nil?
         return if local_time && remote_time.to_i == local_time.to_i

data/lib/plan_my_stuff/comment_metadata.rb

@@ -14,7 +14,7 @@ module PlanMyStuff
       #
       def from_hash(hash)
         metadata = new
-        apply_common_from_hash(metadata, hash)
+        apply_common_from_hash(metadata, hash, PlanMyStuff.configuration.custom_fields_for(:comment))
         metadata.issue_body = hash[:issue_body] || false
 
         metadata
@@ -31,7 +31,13 @@ module PlanMyStuff
       #
       def build(user:, visibility: 'internal', custom_fields: {}, issue_body: false)
         metadata = new
-        apply_common_build(metadata, user: user, visibility: visibility, custom_fields_data: custom_fields)
+        apply_common_build(
+          metadata,
+          user: user,
+          visibility: visibility,
+          custom_fields_data: custom_fields,
+          custom_fields_schema: PlanMyStuff.configuration.custom_fields_for(:comment),
+        )
         metadata.issue_body = issue_body
 
         metadata

data/lib/plan_my_stuff/configuration.rb

@@ -70,19 +70,73 @@ module PlanMyStuff
     # @return [String, nil] recipient address for built-in deferred request notifications
     attr_accessor :deferred_email_to
 
-    # App-defined field definitions stored in issue/comment metadata.
+    # Shared field definitions stored in issue/comment metadata.
     # Keys are field names, values are hashes with :type and :required.
+    # These fields apply to both issues and comments.
     #
     # @return [Hash{Symbol => Hash}]
     #
     attr_accessor :custom_fields
 
+    # Issue-only field definitions, deep-merged on top of shared custom_fields.
+    # Context-specific config wins on key conflicts.
+    #
+    # @return [Hash{Symbol => Hash}]
+    #
+    attr_accessor :issue_custom_fields
+
+    # Comment-only field definitions, deep-merged on top of shared custom_fields.
+    # Context-specific config wins on key conflicts.
+    #
+    # @return [Hash{Symbol => Hash}]
+    #
+    attr_accessor :comment_custom_fields
+
+    # 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 :project_custom_fields
+
     # @return [String, nil] URL prefix for building user-facing ticket URLs in the consuming app
     attr_accessor :issues_url_prefix
 
     # @return [String, nil] name of the consuming app, stored in metadata (e.g. "Atlas")
     attr_accessor :app_name
 
+    # @return [Boolean] whether the release pipeline feature is enabled
+    attr_accessor :pipeline_enabled
+
+    # @return [Integer, nil] GitHub Projects V2 number for the pipeline board (falls back to default_project_number)
+    attr_accessor :pipeline_project_number
+
+    # @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
+
+    # Canonical status name to display alias map. Allows consuming apps to rename
+    # pipeline statuses (e.g. "Submitted" to "Triaged").
+    #
+    # @return [Hash{String => String}]
+    #
+    attr_accessor :pipeline_statuses
+
+    # @return [String] branch name that PRs merge into for "Ready for release" transition
+    attr_accessor :main_branch
+
+    # @return [String] branch name that triggers deployment when a PR merges
+    attr_accessor :production_branch
+
+    # Per-group route mounting toggles. Keys: :webhooks, :issues, :projects.
+    # Set a key to false to skip mounting that route group.
+    #
+    # @return [Hash{Symbol => Boolean}]
+    #
+    attr_accessor :mount_groups
+
     # Named repo configs. Set via config.repos[:element] = 'BrandsInsurance/Element'.
     #
     # @return [Hash{Symbol => String}]
@@ -100,6 +154,14 @@ module PlanMyStuff
       @markdown_options = {}
       @job_classes = {}
       @custom_fields = {}
+      @issue_custom_fields = {}
+      @comment_custom_fields = {}
+      @project_custom_fields = {}
+      @pipeline_enabled = true
+      @pipeline_statuses = {}
+      @main_branch = 'main'
+      @production_branch = 'production'
+      @mount_groups = { webhooks: true, issues: true, projects: true }
     end
 
     # Sets the authentication block for engine controllers.
@@ -132,6 +194,25 @@ module PlanMyStuff
         "Missing required PlanMyStuff configuration: #{missing.join(', ')}",
       )
     end
+
+    # Returns the merged custom fields schema for the given context.
+    # Context-specific fields deep-merge on top of shared fields.
+    #
+    # @param context [Symbol] :issue or :comment
+    #
+    # @return [Hash{Symbol => Hash}]
+    #
+    def custom_fields_for(context)
+      context_fields =
+        case context
+        when :issue then issue_custom_fields
+        when :comment then comment_custom_fields
+        when :project then project_custom_fields
+        else {}
+        end
+
+      custom_fields.deep_merge(context_fields)
+    end
   end
 
   class ConfigurationError < StandardError

data/lib/plan_my_stuff/custom_fields.rb

@@ -1,10 +1,30 @@
 # frozen_string_literal: true
 
+require 'active_model'
+
 module PlanMyStuff
   # Dynamic accessor object for app-defined custom fields stored in metadata.
   # Backed by the config.custom_fields schema, provides both hash-style and
   # method-style access to field values.
+  #
+  # Includes ActiveModel::Validations for type checking, required field
+  # enforcement, and unknown field detection.
   class CustomFields
+    TYPE_MAP = {
+      string: [String],
+      integer: [Integer],
+      boolean: [TrueClass, FalseClass],
+      array: [Array],
+      hash: [Hash],
+    }.freeze
+
+    include ActiveModel::Validations
+
+    validate :validate_custom_fields
+
+    # @return [Hash{Symbol => Hash}]
+    attr_reader :schema
+
     # @param schema [Hash{Symbol => Hash}] field definitions from config.custom_fields
     # @param data [Hash] parsed field data from metadata JSON
     #
@@ -61,5 +81,55 @@ module PlanMyStuff
 
         super
       end
+
+      # @return [void]
+      def validate_custom_fields
+        validate_unknown_fields
+        validate_required_fields
+        validate_field_types
+      end
+
+      # @return [void]
+      def validate_unknown_fields
+        known_keys = @schema.keys
+        @data.each_key do |key|
+          if known_keys.exclude?(key)
+            errors.add(:base, "#{key} is not a recognized custom field")
+          end
+        end
+      end
+
+      # @return [void]
+      def validate_required_fields
+        @schema.each do |field_name, field_config|
+          if field_config[:required] && !@data.key?(field_name)
+            errors.add(:base, "#{field_name} is required")
+          end
+        end
+      end
+
+      # @return [void]
+      def validate_field_types
+        @schema.each do |field_name, field_config|
+          next unless @data.key?(field_name)
+
+          value = @data[field_name]
+          next if value.nil?
+
+          expected_type = field_config[:type]
+          ruby_types = TYPE_MAP[expected_type]
+          next if ruby_types.nil?
+          next if ruby_types.any? { |t| value.is_a?(t) }
+
+          expected_name =
+            if expected_type == :boolean
+              'TrueClass/FalseClass'
+            else
+              ruby_types.first.name
+            end
+
+          errors.add(:base, "#{field_name} must be a #{expected_name}, got #{value.class}")
+        end
+      end
   end
 end

data/lib/plan_my_stuff/issue.rb

@@ -24,8 +24,10 @@ module PlanMyStuff
     attr_accessor :state
     # @return [Array<String>] label names
     attr_accessor :labels
-    # @return [String] resolved repo path (e.g. "Org/Repo")
-    attr_accessor :repo
+    # @return [Time, nil] GitHub's updated_at timestamp
+    attr_reader :updated_at
+    # @return [PlanMyStuff::Repo, nil]
+    attr_reader :repo
 
     class << self
       # Creates a GitHub issue with PMS metadata embedded in the body.
@@ -61,6 +63,7 @@ module PlanMyStuff
           custom_fields: metadata,
         )
         issue_metadata.visibility_allowlist = Array.wrap(visibility_allowlist)
+        issue_metadata.validate_custom_fields!
 
         serialized_body = MetadataParser.serialize(issue_metadata.to_h, '')
 
@@ -68,8 +71,9 @@ module PlanMyStuff
         options[:labels] = labels if labels.any?
 
         result = client.rest(:create_issue, resolved_repo, title, serialized_body, **options)
+        number = read_field(result, :number)
 
-        issue = build(result, repo: resolved_repo)
+        issue = find(number, repo: resolved_repo)
 
         if add_to_project.present?
           project_number = resolve_project_number(add_to_project)
@@ -119,8 +123,11 @@ module PlanMyStuff
           merged_custom_fields = (existing_metadata[:custom_fields] || {}).merge(metadata[:custom_fields] || {})
           existing_metadata = existing_metadata.merge(metadata)
           existing_metadata[:custom_fields] = merged_custom_fields
+          PlanMyStuff::CustomFields.new(
+            PlanMyStuff.configuration.custom_fields_for(:issue),
+            merged_custom_fields,
+          ).validate!
 
-          existing_metadata[:updated_at] = Time.now.utc.iso8601
           options[:body] = MetadataParser.serialize(existing_metadata, '')
         end
 
@@ -244,7 +251,6 @@ module PlanMyStuff
           existing_metadata = parsed[:metadata]
           allowlist = Array.wrap(existing_metadata[:visibility_allowlist])
           existing_metadata[:visibility_allowlist] = yield(allowlist)
-          existing_metadata[:updated_at] = Time.now.utc.iso8601
 
           new_body = MetadataParser.serialize(existing_metadata, parsed[:body])
           client.rest(:update_issue, resolved_repo, number, body: new_body)
@@ -264,16 +270,7 @@ module PlanMyStuff
           body_comment = issue.body_comment
           raise(PlanMyStuff::Error, "No body comment found on issue ##{number}") if body_comment.nil?
 
-          header = body_comment.header
-
-          updated_body =
-            if header.present?
-              "#{header}\n\n#{new_body}"
-            else
-              new_body
-            end
-
-          body_comment.update!(body: updated_body)
+          body_comment.update!(body: new_body)
         end
     end
 
@@ -285,6 +282,11 @@ module PlanMyStuff
       @labels ||= []
     end
 
+    # @param value [PlanMyStuff::Repo, Symbol, String, nil]
+    def repo=(value)
+      @repo = value.present? ? PlanMyStuff::Repo.resolve(value) : nil
+    end
+
     # Persists the issue. Creates if new, updates if persisted.
     #
     # @raise [PlanMyStuff::StaleObjectError] on update if stale
@@ -410,8 +412,9 @@ module PlanMyStuff
         @title = read_field(github_issue, :title)
         @state = read_field(github_issue, :state)
         @raw_body = read_field(github_issue, :body) || ''
+        @updated_at = parse_github_time(safe_read_field(github_issue, :updated_at))
         @labels = extract_labels(github_issue)
-        @repo = repo
+        self.repo = repo
 
         parsed = MetadataParser.parse(@raw_body)
         @metadata = IssueMetadata.from_hash(parsed[:metadata])
@@ -432,6 +435,7 @@ module PlanMyStuff
         @state = other.state
         @body = other.instance_variable_get(:@body)
         @raw_body = other.raw_body
+        @updated_at = other.updated_at
         @labels = other.labels
         @repo = other.repo
         @metadata = other.metadata
@@ -448,11 +452,11 @@ module PlanMyStuff
       #
       def raise_if_stale!
         return if new_record?
-        return if metadata.updated_at.nil?
+        return if updated_at.nil?
 
         remote = self.class.find(number, repo: repo)
-        remote_time = remote.metadata.updated_at
-        local_time = metadata.updated_at
+        remote_time = remote.updated_at
+        local_time = updated_at
 
         return if remote_time.nil?
         return if local_time && remote_time.to_i == local_time.to_i

data/lib/plan_my_stuff/issue_metadata.rb

@@ -22,7 +22,7 @@ module PlanMyStuff
       #
       def from_hash(hash)
         metadata = new
-        apply_common_from_hash(metadata, hash)
+        apply_common_from_hash(metadata, hash, PlanMyStuff.configuration.custom_fields_for(:issue))
 
         metadata.responded_at = parse_time(hash[:responded_at])
         metadata.issues_url = hash[:issues_url]
@@ -42,7 +42,13 @@ module PlanMyStuff
       #
       def build(user:, visibility: 'public', custom_fields: {})
         metadata = new
-        apply_common_build(metadata, user: user, visibility: visibility, custom_fields_data: custom_fields)
+        apply_common_build(
+          metadata,
+          user: user,
+          visibility: visibility,
+          custom_fields_data: custom_fields,
+          custom_fields_schema: PlanMyStuff.configuration.custom_fields_for(:issue),
+        )
 
         metadata.responded_at = nil
         metadata.issues_url = build_issues_url(PlanMyStuff.configuration)

data/lib/plan_my_stuff/markdown.rb

@@ -26,7 +26,7 @@ module PlanMyStuff
         when :redcarpet
           render_redcarpet(text, merged)
         when nil
-          "<code>#{text}</code>"
+          "<code>#{ERB::Util.html_escape(text)}</code>"
         else
           raise(
             ArgumentError,