plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/base_project_item.rb

@@ -0,0 +1,588 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Shared base for GitHub Projects V2 item wrappers. Holds attribute definitions, generic
+  # build/create/move/update/delete/assign machinery, and core instance helpers.
+  #
+  # Not meant to be used directly. Concrete subclasses (ProjectItem, TestingProjectItem) add their own domain-specific
+  # methods.
+  #
+  # Class methods:
+  #   BaseProjectItem.create!(issue)                             -- add existing issue
+  #   BaseProjectItem.create!(title, draft: true, body: "...")  -- create draft item
+  #   BaseProjectItem.move_item!(item_id:, status:)
+  #   BaseProjectItem.assign!(item_id:, assignee:)
+  #
+  # Instance methods:
+  #   item.move_to!("Done")
+  #   item.assign!("octocat")
+  #
+  class BaseProjectItem < PlanMyStuff::ApplicationRecord
+    # @return [String, nil] GitHub node ID (e.g. "PVTI_...")
+    attribute :id, :string
+    # @return [String, nil] node ID of the underlying content (Issue, PR, or DraftIssue)
+    attribute :content_node_id, :string
+    # @return [String, nil] GitHub item type (e.g. "DRAFT_ISSUE", "ISSUE", "PULL_REQUEST")
+    attribute :type, :string
+    # @return [String, nil]
+    attribute :title, :string
+    # @return [String, nil] full body as stored on GitHub (draft items only)
+    attribute :raw_body, :string
+    # @return [String, nil] user-visible body (metadata comment stripped)
+    attribute :body, :string
+    # @return [PlanMyStuff::ProjectItemMetadata] parsed metadata
+    attribute :metadata, default: -> { PlanMyStuff::ProjectItemMetadata.new }
+    # @return [Integer, nil]
+    attribute :number, :integer
+    # @return [String, nil]
+    attribute :url, :string
+    # @return [PlanMyStuff::Repo, nil]
+    attribute :repo
+    # @return [String, nil]
+    attribute :state, :string
+    # @return [String, nil]
+    attribute :status, :string
+    # @return [Time, nil] GitHub's updatedAt timestamp
+    attribute :updated_at, :datetime
+    # @return [Hash]
+    attribute :field_values, default: -> { {} }
+    # @return [Array<String>] GitHub logins assigned to the underlying Issue, PullRequest, or DraftIssue
+    attribute :assignees, default: -> { [] }
+    # @return [PlanMyStuff::BaseProject, nil]
+    attribute :project
+    # @return [PlanMyStuff::Issue, nil] linked issue (nil for draft items)
+    attribute :issue
+
+    class << self
+      # Builds a persisted item from parsed item data.
+      #
+      # @param item_hash [Hash] parsed item data (from BaseProject.parse_project_item)
+      # @param project [PlanMyStuff::BaseProject] parent project
+      #
+      # @return [PlanMyStuff::BaseProjectItem]
+      #
+      def build(item_hash, project:)
+        raw_body_val = item_hash[:body]
+
+        item = new(
+          id: item_hash[:id],
+          type: item_hash[:type],
+          content_node_id: item_hash[:content_node_id],
+          title: item_hash[:title],
+          raw_body: raw_body_val,
+          number: item_hash[:number],
+          url: item_hash[:url],
+          repo: item_hash[:repo],
+          state: item_hash[:state],
+          status: item_hash[:status],
+          updated_at: item_hash[:updated_at],
+          field_values: item_hash[:field_values] || {},
+          assignees: item_hash[:assignees] || [],
+          project: project,
+        )
+
+        if raw_body_val
+          parsed = PlanMyStuff::MetadataParser.parse(raw_body_val)
+          item.metadata = PlanMyStuff::ProjectItemMetadata.from_hash(parsed[:metadata] || {})
+          item.body = parsed[:body]
+        end
+
+        item.instance_variable_set(:@github_response, item_hash[:github_response])
+        item.__send__(:persisted!)
+        item
+      end
+
+      # Creates a project item by adding an existing issue or creating a draft.
+      #
+      # @param issue_or_title [PlanMyStuff::Issue, String] Issue instance (non-draft) or title string (draft)
+      # @param draft [Boolean] when true, creates a draft item from a title string
+      # @param body [String, nil] body for draft items (ignored for non-draft)
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [PlanMyStuff::BaseProjectItem]
+      #
+      def create!(issue_or_title, draft: false, body: nil, project_number: nil, user: nil)
+        item =
+          if draft
+            add_draft_item!(title: issue_or_title, body: body, project_number: project_number)
+          else
+            add_item!(issue: issue_or_title, project_number: project_number)
+          end
+
+        PlanMyStuff::Notifications.instrument('project_item_added', item, user: user)
+        item
+      end
+
+      # Moves a project item to a new status column.
+      #
+      # @param item_id [String] project item ID (e.g. "PVTI_...")
+      # @param status [String] status name, resolved to option ID internally
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [Hash] the updated item
+      #
+      def move_item!(item_id:, status:, project_number: nil)
+        project_number = resolve_default_project_number!(project_number)
+        project = BaseProject.find(project_number)
+
+        status_field = project.status_field
+        option_id = resolve_status_option_id!(status_field, status)
+
+        PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::UPDATE_SINGLE_SELECT_FIELD,
+          variables: {
+            projectId: project.id,
+            itemId: item_id,
+            fieldId: status_field[:id],
+            optionId: option_id,
+          },
+        )
+      end
+
+      # Updates a single-select custom field on a project item.
+      #
+      # @param item_id [String] project item ID (e.g. "PVTI_...")
+      # @param field_name [String] single-select field name (e.g. "Pass Mode")
+      # @param value [String] option name to select
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [Hash] mutation result
+      #
+      def update_single_select_field!(item_id:, field_name:, value:, project_number: nil)
+        project_number = resolve_default_project_number!(project_number)
+        project = BaseProject.find(project_number)
+
+        field = resolve_single_select_field!(project, field_name)
+        option_id = resolve_status_option_id!(field, value)
+
+        PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::UPDATE_SINGLE_SELECT_FIELD,
+          variables: {
+            projectId: project.id,
+            itemId: item_id,
+            fieldId: field[:id],
+            optionId: option_id,
+          },
+        )
+      end
+
+      # Updates a text custom field on a project item.
+      #
+      # @param item_id [String] project item ID (e.g. "PVTI_...")
+      # @param field_name [String] text field name (e.g. "Deployment ID")
+      # @param value [String] text value to set
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [Hash] mutation result
+      #
+      def update_field!(item_id:, field_name:, value:, project_number: nil)
+        project_number = resolve_default_project_number!(project_number)
+        project = BaseProject.find(project_number)
+
+        field = resolve_text_field!(project, field_name)
+
+        PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::UPDATE_TEXT_FIELD,
+          variables: {
+            projectId: project.id,
+            itemId: item_id,
+            fieldId: field[:id],
+            value: value,
+          },
+        )
+      end
+
+      # Updates a date custom field on a project item.
+      #
+      # @param item_id [String] project item ID (e.g. "PVTI_...")
+      # @param field_name [String] date field name (e.g. "Due Date")
+      # @param date [Date, String] date value to set
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [Hash] mutation result
+      #
+      def update_date_field!(item_id:, field_name:, date:, project_number: nil)
+        project_number = resolve_default_project_number!(project_number)
+        project = BaseProject.find(project_number)
+
+        field = resolve_text_field!(project, field_name)
+
+        PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::UPDATE_DATE_FIELD,
+          variables: {
+            projectId: project.id,
+            itemId: item_id,
+            fieldId: field[:id],
+            date: date.to_s,
+          },
+        )
+      end
+
+      # Deletes a project item from its parent project. Returns the +deletedItemId+ from the GraphQL response on
+      # success.
+      #
+      # @raise [PlanMyStuff::APIError] if the GraphQL mutation fails
+      #
+      # @param item_id [String] project item ID (e.g. "PVTI_...")
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [String] the deleted item ID echoed back by GitHub
+      #
+      def delete_item!(item_id:, project_number: nil)
+        project_number = resolve_default_project_number!(project_number)
+        org = PlanMyStuff.configuration.organization
+        project_id = resolve_project_id(org, project_number)
+
+        data = PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::DELETE_PROJECT_ITEM,
+          variables: { projectId: project_id, itemId: item_id },
+        )
+
+        deleted_id = data.dig(:deleteProjectV2Item, :deletedItemId)
+        raise(PlanMyStuff::APIError, "Failed to delete project item #{item_id}") if deleted_id.nil?
+
+        deleted_id
+      end
+
+      # Assigns users to a project item. Issues/PRs use REST via Issue.update!, drafts use GraphQL.
+      #
+      # @raise [PlanMyStuff::APIError] if a username cannot be resolved or the GraphQL mutation fails
+      #
+      # @param number [Integer, nil] issue number (nil for drafts)
+      # @param content_node_id [String] node ID of the underlying content
+      # @param assignees [Array<String>] GitHub usernames
+      # @param draft [Boolean] whether the item is a draft issue
+      # @param repo [Symbol, String, nil] repo key (for issues)
+      #
+      # @return [void]
+      #
+      def assign!(number:, content_node_id:, assignees:, draft: false, repo: nil)
+        if draft
+          client = PlanMyStuff.client
+          user_ids = assignees.map do |assignee|
+            user_data = client.graphql(
+              PlanMyStuff::GraphQL::Queries::USER_NODE_ID,
+              variables: { login: assignee },
+            )
+            user_id = user_data.dig(:user, :id)
+
+            raise(PlanMyStuff::APIError, "GitHub user not found: #{assignee}") if user_id.nil?
+
+            user_id
+          end
+
+          client.graphql(
+            PlanMyStuff::GraphQL::Queries::ASSIGN_DRAFT,
+            variables: { draftIssueId: content_node_id, assigneeIds: user_ids },
+          )
+        else
+          PlanMyStuff::Issue.update!(number: number, repo: repo, assignees: assignees)
+        end
+      end
+
+      private
+
+        # Adds a GitHub issue to a project board.
+        #
+        # @param issue [PlanMyStuff::Issue]
+        # @param project_number [Integer, nil]
+        #
+        # @return [PlanMyStuff::BaseProjectItem]
+        #
+        def add_item!(issue:, project_number:)
+          project_number = resolve_default_project_number!(project_number)
+          client = PlanMyStuff.client
+          org = PlanMyStuff.configuration.organization
+
+          github_issue = client.rest(:issue, issue.repo, issue.number)
+          node_id = github_issue.respond_to?(:node_id) ? github_issue.node_id : github_issue[:node_id]
+
+          project_id = resolve_project_id(org, project_number)
+
+          data = client.graphql(
+            PlanMyStuff::GraphQL::Queries::ADD_ITEM,
+            variables: { projectId: project_id, contentId: node_id },
+          )
+
+          item_data = data.dig(:addProjectV2ItemById, :item) || {}
+          project = BaseProject.find(project_number)
+
+          item = build(
+            {
+              id: item_data[:id],
+              content_node_id: node_id,
+              title: issue.title,
+              number: issue.number,
+              url: nil,
+              state: issue.state,
+              status: nil,
+              field_values: {},
+              github_response: item_data,
+            },
+            project: project,
+          )
+          item.issue = issue
+          item
+        end
+
+        # Adds a draft issue to a project board.
+        #
+        # @param title [String]
+        # @param body [String, nil]
+        # @param project_number [Integer, nil]
+        #
+        # @return [PlanMyStuff::BaseProjectItem]
+        #
+        def add_draft_item!(title:, body:, project_number:)
+          project_number = resolve_default_project_number!(project_number)
+          org = PlanMyStuff.configuration.organization
+          project_id = resolve_project_id(org, project_number)
+
+          variables = { projectId: project_id, title: title }
+          variables[:body] = body if body.present?
+
+          data = PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::ADD_DRAFT_ITEM,
+            variables: variables,
+          )
+
+          item_data = data.dig(:addProjectV2DraftIssue, :projectItem) || {}
+          project = BaseProject.find(project_number)
+
+          build(
+            {
+              id: item_data[:id],
+              content_node_id: item_data.dig(:content, :id),
+              type: 'DRAFT_ISSUE',
+              title: title,
+              body: body,
+              number: nil,
+              url: nil,
+              state: nil,
+              status: nil,
+              field_values: {},
+              github_response: item_data,
+            },
+            project: project,
+          )
+        end
+
+        # @see PlanMyStuff::Project.resolve_default_project_number!
+        def resolve_default_project_number!(project_number)
+          PlanMyStuff::Project.resolve_default_project_number!(project_number)
+        end
+
+        # Finds a text field by name on a project. Raises ArgumentError if the field is not found or is a single-select
+        # field.
+        #
+        # @raise [ArgumentError] if the field is not found or is a single-select field
+        #
+        # @param project [PlanMyStuff::BaseProject]
+        # @param field_name [String]
+        #
+        # @return [Hash]
+        #
+        def resolve_text_field!(project, field_name)
+          field = project.fields.find { |f| f[:name] == field_name && f[:options].nil? }
+
+          if field.nil?
+            available = project.fields.select { |f| f[:options].nil? }.pluck(:name).join(', ')
+            raise(ArgumentError, "Unknown text field '#{field_name}'. Available: #{available}")
+          end
+
+          field
+        end
+
+        # @raise [ArgumentError] if the field is not found or is not a single-select field
+        #
+        # @param project [PlanMyStuff::BaseProject]
+        # @param field_name [String]
+        #
+        # @return [Hash]
+        #
+        def resolve_single_select_field!(project, field_name)
+          field = project.fields.find { |f| f[:name] == field_name && f[:options].present? }
+
+          if field.nil?
+            available = project.fields.select { |f| f[:options].present? }.pluck(:name).join(', ')
+            raise(ArgumentError, "Unknown single-select field '#{field_name}'. Available: #{available}")
+          end
+
+          field
+        end
+
+        # Resolves a status name to its option ID.
+        #
+        # @raise [ArgumentError] if +status_name+ is not a valid option for +status_field+
+        #
+        # @param status_field [Hash]
+        # @param status_name [String]
+        #
+        # @return [String]
+        #
+        def resolve_status_option_id!(status_field, status_name)
+          option = status_field[:options].find { |o| o[:name] == status_name }
+
+          if option.nil?
+            available = status_field[:options].pluck(:name).join(', ')
+            raise(ArgumentError, "Unknown status '#{status_name}'. Available: #{available}")
+          end
+
+          option[:id]
+        end
+
+        # Resolves a project number to its node ID.
+        #
+        # @param org [String]
+        # @param project_number [Integer]
+        #
+        # @return [String]
+        #
+        def resolve_project_id(org, project_number)
+          data = PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::PROJECT_ID,
+            variables: { org: org, number: project_number },
+          )
+
+          data.dig(:organization, :projectV2, :id)
+        end
+    end
+
+    # Moves this item to a new status column on its parent project.
+    #
+    # @param status [String] status name (e.g. "In Progress", "Done")
+    #
+    # @return [Hash] mutation result
+    #
+    def move_to!(status, user: nil)
+      previous_status = self.status
+      result = self.class.move_item!(
+        project_number: project.number,
+        item_id: id,
+        status: status,
+      )
+
+      PlanMyStuff::Notifications.instrument(
+        'project_item_status_changed',
+        self,
+        user: user,
+        status: status,
+        previous_status: previous_status,
+      )
+
+      result
+    end
+
+    # Updates a text custom field on this item.
+    #
+    # @param field_name [String] text field name (e.g. "Deployment ID")
+    # @param value [String] text value to set
+    #
+    # @return [Hash] mutation result
+    #
+    def update_field!(field_name, value)
+      self.class.update_field!(
+        project_number: project.number,
+        item_id: id,
+        field_name: field_name,
+        value: value,
+      )
+    end
+
+    # Updates a single-select custom field on this item.
+    #
+    # @param field_name [String] single-select field name (e.g. "Testing")
+    # @param value [String] option name to select
+    #
+    # @return [Hash] mutation result
+    #
+    def update_single_select_field!(field_name, value)
+      self.class.update_single_select_field!(
+        project_number: project.number,
+        item_id: id,
+        field_name: field_name,
+        value: value,
+      )
+    end
+
+    # Deletes this item from its parent project. Marks the in-memory instance as destroyed so +destroyed?+ returns
+    # true and +persisted?+ returns false.
+    #
+    # No-op if the instance is already destroyed.
+    #
+    # @return [String, nil] the deleted item ID, or nil if already destroyed
+    #
+    def destroy!(user: nil)
+      return if destroyed?
+
+      deleted_id = self.class.delete_item!(
+        project_number: project.number,
+        item_id: id,
+      )
+
+      PlanMyStuff::Notifications.instrument('project_item_removed', self, user: user)
+      destroyed!
+      deleted_id
+    end
+
+    # Assigns users to this item on its parent project. For draft items the underlying call uses the draft-issue
+    # assign mutation; for issue-backed items it delegates to +Issue.update!+ with +assignees:+.
+    #
+    # @param assignees [String, Array<String>] GitHub username(s)
+    #
+    # @return [void]
+    #
+    def assign!(assignees, user: nil)
+      assignee_list = Array.wrap(assignees)
+
+      self.class.assign!(
+        number: number,
+        content_node_id: content_node_id,
+        assignees: assignee_list,
+        draft: draft?,
+        repo: repo,
+      )
+
+      PlanMyStuff::Notifications.instrument(
+        'project_item_assigned',
+        self,
+        user: user,
+        assignees: assignee_list,
+      )
+    end
+
+    # Serializes the project item to a JSON-safe hash, excluding the back-reference to the parent project to prevent
+    # recursive serialization cycles.
+    #
+    # @return [Hash]
+    #
+    def as_json(options = {})
+      merged_except = Array.wrap(options[:except]) + ['project']
+      merged_methods = Array.wrap(options[:methods]) + [:draft?]
+      super(options.merge(except: merged_except, methods: merged_methods)).merge(
+        'project_id' => project&.id,
+        'project_number' => project&.number,
+      )
+    end
+
+    # @return [Boolean]
+    def draft?
+      type == 'DRAFT_ISSUE'
+    end
+
+    # @return [void]
+    def issue=(val)
+      @issue_assigned = true
+      super
+    end
+
+    # @return [PlanMyStuff::Issue, nil]
+    def issue
+      return super if @issue_assigned
+      return if draft?
+
+      self.issue = PlanMyStuff::Issue.find(number, repo: repo)
+      super
+    end
+  end
+end

data/lib/plan_my_stuff/base_project_metadata.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Shared base for project-style metadata (regular and testing). Holds the
+  # +kind+ dispatch field and serialization hook. Not instantiated directly;
+  # use +ProjectMetadata+ or +TestingProjectMetadata+.
+  class BaseProjectMetadata < PlanMyStuff::BaseMetadata
+    # @return [String, nil] dispatch key: "project" or "testing"
+    attr_accessor :kind
+
+    # @return [Hash]
+    def to_h
+      super.merge(kind: kind)
+    end
+  end
+end