plan_my_stuff 0.1.0

data/lib/generators/plan_my_stuff/views/views_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Generators
+    class ViewsGenerator < Rails::Generators::Base
+      source_root PlanMyStuff::Engine.root.join('app', 'views', 'plan_my_stuff')
+
+      # @return [void]
+      def copy_views
+        directory('.', 'app/views/plan_my_stuff')
+      end
+
+      # @return [void]
+      def show_done
+        say('')
+        say('PlanMyStuff views copied to app/views/plan_my_stuff/.', :green)
+        say('You can now customize these templates to match your app.', :yellow)
+        say('')
+      end
+    end
+  end
+end

data/lib/plan_my_stuff/application_record.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+module PlanMyStuff
+  # Base class for all PMS domain objects backed by GitHub resources.
+  # Provides shared persistence predicates and utility helpers.
+  class ApplicationRecord
+    include ActiveModel::Model
+
+    def initialize(**)
+      super
+      @persisted = false
+    end
+
+    # @return [Boolean]
+    def persisted?
+      @persisted
+    end
+
+    # @return [Boolean]
+    def new_record?
+      !@persisted
+    end
+
+    private
+
+      # Reads a field from an object that may respond to method calls or hash access.
+      #
+      # @param obj [Object]
+      # @param field [Symbol]
+      #
+      # @return [Object]
+      #
+      def read_field(obj, field)
+        obj.respond_to?(field) ? obj.public_send(field) : obj[field]
+      end
+  end
+end

data/lib/plan_my_stuff/base_metadata.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module PlanMyStuff
+  class BaseMetadata
+    SCHEMA_VERSION = '1'
+
+    # @return [String] schema version for forward compatibility (starts at "1")
+    attr_accessor :schema_version
+    # @return [String] gem version that created this metadata
+    attr_accessor :gem_version
+    # @return [String, nil] Rails environment
+    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"
+    attr_accessor :visibility
+    # @return [PlanMyStuff::CustomFields, nil] app-defined custom field values
+    attr_accessor :custom_fields
+
+    class << self
+      private
+
+        # Sets common fields on a metadata instance from a parsed hash
+        #
+        # @param metadata [BaseMetadata]
+        # @param hash [Hash]
+        #
+        # @return [void]
+        #
+        def apply_common_from_hash(metadata, hash)
+          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,
+            hash[:custom_fields] || {},
+          )
+        end
+
+        # Sets common fields on a metadata instance for new creation
+        #
+        # @param metadata [BaseMetadata]
+        # @param user [Object, Integer] user object or user_id
+        # @param visibility [String] "public" or "internal"
+        # @param custom_fields_data [Hash]
+        #
+        # @return [void]
+        #
+        def apply_common_build(metadata, user:, visibility: 'internal', custom_fields_data: {})
+          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_data,
+          )
+        end
+
+        # @return [Time, nil]
+        def parse_time(value)
+          return if value.nil?
+          return value.utc if value.is_a?(Time)
+
+          Time.parse(value.to_s).utc
+        rescue ArgumentError
+          nil
+        end
+    end
+
+    def initialize
+      @visibility = 'internal'
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        schema_version: schema_version,
+        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,
+      }
+    end
+
+    # @return [Boolean]
+    def internal?
+      visibility == 'internal'
+    end
+
+    # @return [Boolean]
+    def public?
+      visibility == 'public'
+    end
+
+    # @return [String]
+    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/client.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/keys'
+require 'octokit'
+
+module PlanMyStuff
+  # Infrastructure wrapper around Octokit. Handles auth, error normalization,
+  # and repo resolution. Domain modules (Issues, Projects, etc.) use this
+  # internally via PlanMyStuff.client.
+  class Client
+    # @return [Octokit::Client]
+    attr_reader :octokit
+
+    # @return [Client]
+    def initialize
+      PlanMyStuff.configuration.validate!
+
+      @octokit = Octokit::Client.new(access_token: PlanMyStuff.configuration.access_token)
+    end
+
+    # Delegates a REST API call to Octokit, normalizing errors.
+    #
+    # @param method [Symbol] Octokit method name (e.g. :create_issue)
+    # @param args [Array] positional arguments
+    # @param kwargs [Hash] keyword arguments
+    #
+    # @return [Object] Octokit response
+    #
+    def rest(method, *, **kwargs, &)
+      if kwargs.empty?
+        octokit.public_send(method, *, &)
+      else
+        octokit.public_send(method, *, **kwargs, &)
+      end
+    rescue Octokit::TooManyRequests => e
+      raise_rate_limit_error(e)
+    rescue Octokit::ClientError, Octokit::ServerError => e
+      raise(APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+    end
+
+    # Executes a GraphQL query against GitHub's /graphql endpoint.
+    #
+    # @param query [String] GraphQL query string
+    # @param variables [Hash] GraphQL variables
+    #
+    # @return [Hash] parsed response data
+    #
+    def graphql(query, variables: {})
+      payload = { query: query }
+      payload[:variables] = variables unless variables.empty?
+
+      response = octokit.post('/graphql', payload.to_json)
+      data =
+        if response.is_a?(Hash)
+          response
+        else
+          (response.respond_to?(:to_h) ? response.to_h : response)
+        end
+
+      data = data.deep_symbolize_keys if data.respond_to?(:deep_symbolize_keys)
+
+      check_graphql_errors!(data)
+
+      data[:data]
+    rescue Octokit::TooManyRequests => e
+      raise_rate_limit_error(e)
+    rescue Octokit::ClientError, Octokit::ServerError => e
+      raise(APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+    end
+
+    # Resolves a repo param to a full "Org/Repo" string.
+    #
+    # @param repo [Symbol, String, nil] repo key, full string, 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
+    end
+
+    private
+
+      # @param data [Hash] parsed GraphQL response
+      #
+      # @raise [GraphQLError] if response contains errors
+      #
+      # @return [void]
+      #
+      def check_graphql_errors!(data)
+        errors = data[:errors]
+        return if errors.blank?
+
+        messages = errors.filter_map { |e| e[:message] }
+        raise(GraphQLError.new(messages.join('; '), errors: errors))
+      end
+
+      # @param exception [Octokit::TooManyRequests]
+      #
+      # @raise [RateLimitError]
+      #
+      def raise_rate_limit_error(exception)
+        retry_after = parse_retry_after(exception)
+        raise(RateLimitError.new(exception.message, retry_after: retry_after))
+      end
+
+      # @param exception [Octokit::TooManyRequests]
+      #
+      # @return [Time, nil]
+      #
+      def parse_retry_after(exception)
+        headers = exception.response_headers
+        return unless headers
+
+        if headers['retry-after']
+          Time.now.utc + headers['retry-after'].to_i
+        elsif headers['x-ratelimit-reset']
+          Time.at(headers['x-ratelimit-reset'].to_i).utc
+        end
+      end
+  end
+end

data/lib/plan_my_stuff/comment.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Wraps a GitHub comment with parsed PMS metadata.
+  # Class methods provide the public API for CRUD operations.
+  #
+  # Follows an ActiveRecord-style pattern:
+  # - `Comment.new(**attrs)` creates an unpersisted instance
+  # - `Comment.create!` / `Comment.list` return persisted instances
+  # - `comment.save!` / `comment.update!` / `comment.reload` for persistence
+  class Comment < PlanMyStuff::ApplicationRecord
+    # @return [Integer] GitHub comment ID
+    attr_reader :id
+    # @return [String] full body as stored on GitHub
+    attr_reader :raw_body
+    # @return [PlanMyStuff::CommentMetadata] parsed metadata (empty when no PMS metadata present)
+    attr_reader :metadata
+
+    # @return [String] comment body without the metadata HTML comment
+    attr_accessor :body
+    # @return [PlanMyStuff::Issue] parent issue
+    attr_accessor :issue
+    # @param value [Symbol, String, nil]
+    attr_writer :visibility
+
+    class << self
+      # Creates a comment on a GitHub issue with PMS metadata and a visible header.
+      #
+      # @param issue [PlanMyStuff::Issue] parent issue
+      # @param body [String]
+      # @param user [Object, Integer] user object or user_id
+      # @param visibility [Symbol] :public or :internal
+      # @param custom_fields [Hash]
+      # @param issue_body [Boolean] whether this comment holds the issue body
+      #
+      # @return [PlanMyStuff::Comment]
+      #
+      def create!(
+        issue:,
+        body:,
+        user: nil,
+        visibility: :public,
+        custom_fields: {},
+        skip_responded: false,
+        issue_body: false
+      )
+        resolved_user = UserResolver.resolve(user)
+        visibility = resolve_visibility(visibility, resolved_user)
+        comment_metadata = CommentMetadata.build(
+          user: resolved_user,
+          visibility: visibility.to_s,
+          custom_fields: custom_fields,
+          issue_body: issue_body,
+        )
+
+        header = build_header(resolved_user)
+        full_body = "#{header}\n\n#{body}"
+        serialized_body = MetadataParser.serialize(comment_metadata.to_h, full_body)
+
+        result = PlanMyStuff.client.rest(:add_comment, issue.repo, issue.number, serialized_body)
+
+        mark_issue_responded_if_first_support_comment(issue, resolved_user) unless skip_responded
+
+        build(result, issue: issue)
+      end
+
+      # Updates an existing GitHub comment body.
+      #
+      # @param id [Integer] comment ID
+      # @param repo [String] repo path
+      # @param body [String] new serialized body
+      #
+      # @return [Object] Octokit response
+      #
+      def update!(id:, repo:, body:)
+        PlanMyStuff.client.rest(:update_comment, repo, id, body)
+      end
+
+      # Finds a single comment by ID, given its parent issue.
+      #
+      # @param id [Integer] GitHub comment ID
+      # @param issue [PlanMyStuff::Issue] parent issue
+      #
+      # @return [PlanMyStuff::Comment]
+      #
+      def find(id, issue:)
+        github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
+        build(github_comment, issue: issue)
+      end
+
+      # Lists comments on a GitHub issue, optionally filtering to PMS-only comments.
+      #
+      # @param issue [PlanMyStuff::Issue] parent issue
+      # @param pms_only [Boolean]
+      #
+      # @return [Array<PlanMyStuff::Comment>]
+      #
+      def list(issue:, pms_only: false)
+        github_comments = PlanMyStuff.client.rest(:issue_comments, issue.repo, issue.number)
+        comments = github_comments.map { |gc| build(gc, issue: issue) }
+
+        pms_only ? comments.select(&:pms_comment?) : comments
+      end
+
+      private
+
+        # Hydrates a Comment from a GitHub API response.
+        #
+        # @param github_comment [Object] Octokit comment response
+        # @param issue [PlanMyStuff::Issue] parent issue
+        #
+        # @return [PlanMyStuff::Comment]
+        #
+        def build(github_comment, issue:)
+          comment = new
+          comment.__send__(:hydrate_from_github, github_comment, issue: issue)
+          comment
+        end
+
+        # Builds the visible header for a comment.
+        #
+        # @param user [Object, nil] resolved user object
+        #
+        # @return [String]
+        #
+        def build_header(user)
+          display_name =
+            if user.present?
+              UserResolver.display_name(user)
+            else
+              'Unknown'
+            end
+
+          timestamp = Time.now.utc.strftime('%m/%d/%Y %H:%M')
+          "### #{display_name} at #{timestamp}:"
+        end
+
+        # Coerces visibility to :public unless the user is support.
+        #
+        # @param visibility [Symbol] requested visibility
+        # @param user [Object, nil] resolved user object
+        #
+        # @return [Symbol] :public or :internal
+        #
+        def resolve_visibility(visibility, user)
+          return :public unless visibility.to_sym == :internal
+
+          return :public if user.blank?
+
+          return :public unless UserResolver.support?(user)
+
+          :internal
+        end
+
+        # Sets responded_at on the issue metadata if this is the first support
+        # comment and the issue hasn't been responded to yet.
+        #
+        # @param issue [PlanMyStuff::Issue] parent issue
+        # @param user [Object, nil] resolved user object
+        #
+        # @return [void]
+        #
+        def mark_issue_responded_if_first_support_comment(issue, user)
+          return if user.nil?
+
+          return unless UserResolver.support?(user)
+          return unless issue.pms_issue?
+
+          return if issue.metadata.responded?
+
+          Issue.update!(
+            number: issue.number,
+            repo: issue.repo,
+            metadata: { responded_at: Time.now.utc.iso8601 },
+          )
+        end
+    end
+
+    def initialize(**attrs)
+      @id = attrs.delete(:id)
+      @raw_body = nil
+      @metadata = CommentMetadata.new
+      super
+    end
+
+    # Persists the comment. Creates if new, updates if persisted.
+    #
+    # @raise [PlanMyStuff::StaleObjectError] on update if stale
+    #
+    # @return [self]
+    #
+    def save!
+      if new_record?
+        created = self.class.create!(
+          issue: issue,
+          body: body,
+          visibility: visibility || :public,
+        )
+        hydrate_from_comment(created)
+      else
+        update!(body: body)
+      end
+
+      self
+    end
+
+    # Updates this comment on GitHub. Raises StaleObjectError if the remote
+    # has been modified since this instance was loaded.
+    #
+    # @param attrs [Hash] attributes to update (body:, visibility:)
+    #
+    # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
+    #
+    # @return [self]
+    #
+    def update!(**attrs)
+      raise_if_stale!
+
+      new_body = attrs[:body] || 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)
+      self.class.update!(id: id, repo: issue.repo, body: serialized)
+
+      reload
+    end
+
+    # Re-fetches this comment from GitHub and updates all local attributes.
+    #
+    # @return [self]
+    #
+    def reload
+      github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
+      hydrate_from_github(github_comment, issue: issue)
+      self
+    end
+
+    # @return [Boolean]
+    def pms_comment?
+      metadata.schema_version.present?
+    end
+
+    # Returns the comment visibility as a symbol.
+    # Uses the locally set value if present, otherwise falls back to metadata.
+    #
+    # @return [Symbol, nil] :public or :internal
+    #
+    def visibility
+      @visibility || metadata.visibility&.to_sym
+    end
+
+    # Checks if the comment is visible to the given user.
+    # Public PMS comments: visible to everyone the parent issue is visible to.
+    # Internal PMS comments: visible only to support users.
+    # Non-PMS comments: visible only to support users.
+    #
+    # @param user [Object, Integer] user object or user_id
+    #
+    # @return [Boolean]
+    #
+    def visible_to?(user)
+      resolved = PMS::UserResolver.resolve(user)
+
+      if pms_comment?
+        issue.visible_to?(resolved) && (visibility != :internal || PMS::UserResolver.support?(resolved))
+      else
+        PMS::UserResolver.support?(resolved)
+      end
+    end
+
+    # Extracts the `### Name at timestamp:` header line from the comment body.
+    #
+    # @return [String, nil]
+    #
+    def header
+      match = (body || '').match(/\A(###\s.+?:\s*)\n/)
+      match&.captures&.first&.strip
+    end
+
+    # Returns the comment body with the header stripped.
+    #
+    # @return [String]
+    #
+    def body_without_header
+      (body || '').sub(/\A###\s.+?:\s*\n\n/, '')
+    end
+
+    private
+
+      # Populates this instance from a GitHub API response.
+      #
+      # @param github_comment [Object] Octokit comment response
+      # @param issue [PlanMyStuff::Issue] parent issue
+      #
+      # @return [void]
+      #
+      def hydrate_from_github(github_comment, issue:)
+        @id = read_field(github_comment, :id)
+        @raw_body = read_field(github_comment, :body)
+        @issue = issue
+
+        parsed = MetadataParser.parse(@raw_body)
+        @metadata = CommentMetadata.from_hash(parsed[:metadata])
+        @body = parsed[:body]
+        @visibility = @metadata.visibility&.to_sym
+        @persisted = true
+      end
+
+      # Copies attributes from another Comment instance into self.
+      #
+      # @param other [PlanMyStuff::Comment]
+      #
+      # @return [void]
+      #
+      def hydrate_from_comment(other)
+        @id = other.id
+        @body = other.body
+        @raw_body = other.raw_body
+        @issue = other.issue
+        @metadata = other.metadata
+        @visibility = other.visibility
+        @persisted = true
+      end
+
+      # Raises StaleObjectError if the remote comment has been modified
+      # since this instance was loaded.
+      #
+      # @raise [PlanMyStuff::StaleObjectError]
+      #
+      # @return [void]
+      #
+      def raise_if_stale!
+        return if new_record?
+        return if metadata.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
+
+        return if remote_time.nil?
+        return if local_time && remote_time.to_i == local_time.to_i
+
+        raise(StaleObjectError.new(
+          "Comment ##{id} has been modified remotely",
+          local_updated_at: local_time,
+          remote_updated_at: remote_time,
+        ))
+      end
+  end
+end