plan_my_stuff 0.1.0

data/lib/plan_my_stuff/comment_metadata.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class CommentMetadata < BaseMetadata
+    # @return [Boolean] true if this comment holds the issue's body content
+    attr_accessor :issue_body
+
+    class << self
+      # Builds a CommentMetadata from a parsed hash (e.g. from MetadataParser)
+      #
+      # @param hash [Hash]
+      #
+      # @return [CommentMetadata]
+      #
+      def from_hash(hash)
+        metadata = new
+        apply_common_from_hash(metadata, hash)
+        metadata.issue_body = hash[:issue_body] || false
+
+        metadata
+      end
+
+      # Builds a new CommentMetadata for comment creation, auto-filling gem defaults
+      #
+      # @param user [Object, Integer] user object or user_id
+      # @param visibility [String] "public" or "internal"
+      # @param custom_fields [Hash] app-defined field values
+      # @param issue_body [Boolean] whether this comment holds the issue body
+      #
+      # @return [CommentMetadata]
+      #
+      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)
+        metadata.issue_body = issue_body
+
+        metadata
+      end
+    end
+
+    def initialize
+      super
+      @issue_body = false
+    end
+
+    # @return [Boolean]
+    def issue_body?
+      issue_body == true
+    end
+
+    # @return [Hash]
+    def to_h
+      super.merge(issue_body: issue_body)
+    end
+  end
+end

data/lib/plan_my_stuff/configuration.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class Configuration
+    # @return [String] GitHub PAT with repo and project scopes. Required.
+    attr_accessor :access_token
+
+    # @return [String] GitHub organization name. Required.
+    attr_accessor :organization
+
+    # @return [Symbol, nil] default repo key used when callers omit repo: param
+    attr_accessor :default_repo
+
+    # @return [Integer, nil] default GitHub Projects V2 number for add_to_project calls
+    attr_accessor :default_project_number
+
+    # @return [String] consuming app's user model class name, constantized for lookups
+    attr_accessor :user_class
+
+    # @return [Symbol] method called on user object to get display name for comment headers
+    attr_accessor :display_name_method
+
+    # @return [Symbol] method called on user object to extract the app-side user ID
+    attr_accessor :user_id_method
+
+    # Determines if a user is support staff. Symbol (method name on user) or Proc that
+    # receives the user object and returns boolean.
+    #
+    # @return [Symbol, Proc]
+    #
+    attr_accessor :support_method
+
+    # @return [Symbol] which markdown gem to use: :commonmarker or :redcarpet
+    attr_accessor :markdown_renderer
+
+    # Default options passed to the markdown renderer. Per-call options in
+    # Markdown.render merge on top of these.
+    #
+    # For :commonmarker - passed as `options:` to `Commonmarker.to_html`
+    #   e.g. `{ render: { hardbreaks: true } }`
+    #
+    # For :redcarpet - :render_options and :renderer are extracted for the HTML renderer;
+    #   remaining keys are passed as extensions to `Redcarpet::Markdown.new`
+    #   e.g. `{ render_options: { hard_wrap: true, no_styles: true }, autolink: true }`
+    #
+    # @return [Hash]
+    #
+    attr_accessor :markdown_options
+
+    # Proc returning boolean, or nil (always send). When it returns false the request is
+    # deferred to a background job instead of hitting GitHub.
+    #
+    # @return [Proc, nil]
+    #
+    attr_accessor :should_send_request
+
+    # Map of action type to job class name for deferred requests.
+    # Keys: :create_ticket, :post_comment, :update_status.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    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
+
+    # App-defined field definitions stored in issue/comment metadata.
+    # Keys are field names, values are hashes with :type and :required.
+    #
+    # @return [Hash{Symbol => Hash}]
+    #
+    attr_accessor :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
+
+    # Named repo configs. Set via config.repos[:element] = 'BrandsInsurance/Element'.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    attr_reader :repos
+
+    # @return [Configuration]
+    def initialize
+      @repos = {}
+      @user_class = 'User'
+      @display_name_method = :to_s
+      @user_id_method = :id
+      @support_method = :support?
+      @markdown_renderer = :commonmarker
+      @markdown_options = {}
+      @job_classes = {}
+      @custom_fields = {}
+    end
+
+    # Sets the authentication block for engine controllers.
+    #
+    # @return [void]
+    #
+    def authenticate_with(&block)
+      if block
+        @authenticate_with = block
+      else
+        @authenticate_with
+      end
+    end
+
+    # Validates that required configuration options are set.
+    #
+    # @raise [ConfigurationError] if required options are missing
+    #
+    # @return [void]
+    #
+    def validate!
+      missing = []
+      missing << 'access_token' if access_token.nil? || access_token.to_s.strip.empty?
+      missing << 'organization' if organization.nil? || organization.to_s.strip.empty?
+
+      return if missing.empty?
+
+      raise(
+        ConfigurationError,
+        "Missing required PlanMyStuff configuration: #{missing.join(', ')}",
+      )
+    end
+  end
+
+  class ConfigurationError < StandardError
+  end
+end

data/lib/plan_my_stuff/custom_fields.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+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.
+  class CustomFields
+    # @param schema [Hash{Symbol => Hash}] field definitions from config.custom_fields
+    # @param data [Hash] parsed field data from metadata JSON
+    #
+    def initialize(schema, data = {})
+      @schema = schema || {}
+      @data = (data || {}).transform_keys(&:to_sym)
+    end
+
+    # @param key [Symbol, String]
+    #
+    # @return [Object]
+    #
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    # @param key [Symbol, String]
+    # @param value [Object]
+    #
+    # @return [Object]
+    #
+    def []=(key, value)
+      @data[key.to_sym] = value
+    end
+
+    # @return [Hash]
+    def to_h
+      @data.dup
+    end
+
+    # @return [String]
+    def to_json(...)
+      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
+
+      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]
+        end
+
+        super
+      end
+  end
+end

data/lib/plan_my_stuff/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Base error for all PlanMyStuff errors
+  class Error < StandardError
+  end
+
+  # Raised when GitHub REST API returns a non-success HTTP status
+  class APIError < Error
+    # @return [Integer]
+    attr_reader :status
+
+    # @param message [String]
+    # @param status [Integer]
+    #
+    def initialize(message = nil, status: nil)
+      @status = status
+      super(message)
+    end
+  end
+
+  # Raised when GitHub GraphQL API returns errors in the response body
+  class GraphQLError < Error
+    # @return [Array<Hash>]
+    attr_reader :errors
+
+    # @param message [String]
+    # @param errors [Array<Hash>]
+    #
+    def initialize(message = nil, errors: [])
+      @errors = errors
+      super(message)
+    end
+  end
+
+  # Raised when GitHub rate limit is exhausted (429 or rate limit headers)
+  class RateLimitError < Error
+    # @return [Time]
+    attr_reader :retry_after
+
+    # @param message [String]
+    # @param retry_after [Time]
+    #
+    def initialize(message = nil, retry_after: nil)
+      @retry_after = retry_after
+      super(message)
+    end
+  end
+
+  # Raised when an object has been modified remotely since it was loaded
+  class StaleObjectError < Error
+    # @return [Time, nil]
+    attr_reader :local_updated_at
+
+    # @return [Time, nil]
+    attr_reader :remote_updated_at
+
+    # @param message [String]
+    # @param local_updated_at [Time, nil]
+    # @param remote_updated_at [Time, nil]
+    #
+    def initialize(message = nil, local_updated_at: nil, remote_updated_at: nil)
+      @local_updated_at = local_updated_at
+      @remote_updated_at = remote_updated_at
+      super(message)
+    end
+  end
+
+  # Raised when custom field validation fails (Phase 1)
+  class ValidationError < Error
+    # @return [String, nil]
+    attr_reader :field
+
+    # @return [Symbol, nil]
+    attr_reader :expected_type
+
+    # @param message [String]
+    # @param field [String, nil]
+    # @param expected_type [Symbol, nil]
+    #
+    def initialize(message = nil, field: nil, expected_type: nil)
+      @field = field
+      @expected_type = expected_type
+      super(message)
+    end
+  end
+end