plan_my_stuff 0.1.1 → 0.3.0

data/lib/plan_my_stuff/project.rb

@@ -18,11 +18,21 @@ module PlanMyStuff
     attr_reader :number
     # @return [Boolean] whether the project is closed
     attr_reader :closed
+    # @return [PlanMyStuff::ProjectMetadata] parsed metadata (empty when no PMS metadata present)
+    attr_reader :metadata
+    # @return [String] full readme as stored on GitHub
+    attr_reader :raw_readme
+    # @return [String, nil] project short description (from shortDescription)
+    attr_reader :description
+    # @return [Time, nil] GitHub's updatedAt timestamp
+    attr_reader :updated_at
 
     # @return [String] project title
     attr_accessor :title
     # @return [String] project URL
     attr_accessor :url
+    # @return [String, nil] user-visible readme content (without metadata comment)
+    attr_accessor :readme
     # @return [Array<Hash>] status options ({id:, name:})
     attr_accessor :statuses
     # @return [Array<Hash>] all field definitions
@@ -35,25 +45,97 @@ module PlanMyStuff
     attr_accessor :has_next_page
 
     class << self
-      # Creates a new project in the configured organization.
+      # Creates a new project in the configured organization with PMS metadata.
       #
       # @param title [String]
+      # @param user [Object, Integer, nil] user object or user_id
+      # @param visibility [String] "public" or "internal"
+      # @param custom_fields [Hash] app-defined field values
+      # @param readme [String] user-visible readme content
+      # @param description [String, nil] project short description
       #
-      # @return [Object]
+      # @return [PlanMyStuff::Project]
       #
-      def create(title:)
-        raise(NotImplementedError, "#{name}.create is not yet implemented")
+      def create!(title:, user: nil, visibility: 'internal', custom_fields: {}, readme: '', description: nil)
+        org = PlanMyStuff.configuration.organization
+
+        project_metadata = PlanMyStuff::ProjectMetadata.build(
+          user: user,
+          visibility: visibility,
+          custom_fields: custom_fields,
+        )
+        project_metadata.validate_custom_fields!
+
+        org_id = resolve_org_id(org)
+        data = PlanMyStuff.client.graphql(
+          create_mutation,
+          variables: { input: { ownerId: org_id, title: title } },
+        )
+
+        new_project = data.dig(:createProjectV2, :projectV2) || {}
+        project_id = new_project[:id]
+        project_number = new_project[:number]
+
+        serialized_readme = PlanMyStuff::MetadataParser.serialize(project_metadata.to_h, readme)
+        update_input = { projectId: project_id, readme: serialized_readme }
+        update_input[:shortDescription] = description if description.present?
+
+        PlanMyStuff.client.graphql(
+          update_mutation,
+          variables: { input: update_input },
+        )
+
+        find(project_number)
       end
 
       # Updates an existing project.
       #
       # @param project_number [Integer]
       # @param title [String, nil]
+      # @param readme [String, nil] user-visible readme content (metadata preserved)
+      # @param description [String, nil] project short description
+      # @param metadata [Hash, nil] custom fields to merge into existing metadata
       #
-      # @return [Object]
+      # @return [PlanMyStuff::Project]
       #
-      def update(project_number:, title: nil)
-        raise(NotImplementedError, "#{name}.update is not yet implemented")
+      def update!(project_number:, title: nil, readme: nil, description: nil, metadata: nil)
+        org = PlanMyStuff.configuration.organization
+        project_id = resolve_project_id(org, project_number)
+
+        update_input = { projectId: project_id }
+        update_input[:title] = title unless title.nil?
+        update_input[:shortDescription] = description unless description.nil?
+
+        if metadata.present? || !readme.nil?
+          current = find(project_number)
+          parsed = PlanMyStuff::MetadataParser.parse(current.raw_readme)
+          existing_metadata = parsed[:metadata]
+
+          if metadata.present?
+            # Seed with fresh metadata when project has no existing PMS metadata
+            if existing_metadata[:schema_version].blank?
+              existing_metadata = PlanMyStuff::ProjectMetadata.build(user: nil).to_h
+            end
+
+            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(:project),
+              merged_custom_fields,
+            ).validate!
+          end
+
+          body = readme.nil? ? parsed[:body] : readme
+          update_input[:readme] = PlanMyStuff::MetadataParser.serialize(existing_metadata, body)
+        end
+
+        PlanMyStuff.client.graphql(
+          update_mutation,
+          variables: { input: update_input },
+        )
+
+        find(project_number)
       end
 
       # Lists all projects in the configured organization.
@@ -90,20 +172,20 @@ module PlanMyStuff
         end
       end
 
-      private
+      # Resolves a project number, falling back to config.default_project_number.
+      #
+      # @param project_number [Integer, nil]
+      #
+      # @return [Integer]
+      #
+      def resolve_default_project_number(project_number)
+        return project_number if project_number.present?
 
-        # Resolves a project number, falling back to config.default_project_number.
-        #
-        # @param project_number [Integer, nil]
-        #
-        # @return [Integer]
-        #
-        def resolve_default_project_number(project_number)
-          return project_number if project_number.present?
+        PlanMyStuff.configuration.default_project_number ||
+          raise(ArgumentError, 'project_number is required when config.default_project_number is not set')
+      end
 
-          PlanMyStuff.configuration.default_project_number ||
-            raise(ArgumentError, 'project_number is required when config.default_project_number is not set')
-        end
+      private
 
         # @return [String]
         def list_query
@@ -115,8 +197,10 @@ module PlanMyStuff
                     id
                     number
                     title
+                    shortDescription
                     url
                     closed
+                    updatedAt
                   }
                 }
               }
@@ -133,8 +217,11 @@ module PlanMyStuff
                   id
                   number
                   title
+                  shortDescription
+                  readme
                   url
                   closed
+                  updatedAt
                   fields(first: 50) {
                     nodes {
                       ... on ProjectV2SingleSelectField {
@@ -170,6 +257,7 @@ module PlanMyStuff
                           number
                           url
                           state
+                          repository { nameWithOwner }
                         }
                         ... on PullRequest {
                           id
@@ -177,6 +265,7 @@ module PlanMyStuff
                           number
                           url
                           state
+                          repository { nameWithOwner }
                         }
                         ... on DraftIssue {
                           id
@@ -342,6 +431,7 @@ module PlanMyStuff
         def parse_project_item(item)
           content = item[:content] || {}
           field_values = item.dig(:fieldValues, :nodes) || []
+          repo_name = content.dig(:repository, :nameWithOwner)
 
           {
             id: item[:id],
@@ -351,6 +441,7 @@ module PlanMyStuff
             number: content[:number],
             url: content[:url],
             state: content[:state],
+            repo: repo_name.present? ? PlanMyStuff::Repo.resolve(repo_name) : nil,
             status: extract_item_status(field_values),
             field_values: parse_field_values(field_values),
           }
@@ -404,6 +495,60 @@ module PlanMyStuff
 
           data.dig(:organization, :projectV2, :id)
         end
+
+        # Resolves an organization login to its node ID.
+        #
+        # @param org [String]
+        #
+        # @return [String]
+        #
+        def resolve_org_id(org)
+          data = PlanMyStuff.client.graphql(
+            org_id_query,
+            variables: { org: org },
+          )
+
+          data.dig(:organization, :id)
+        end
+
+        # @return [String]
+        def org_id_query
+          <<~GRAPHQL
+            query($org: String!) {
+              organization(login: $org) {
+                id
+              }
+            }
+          GRAPHQL
+        end
+
+        # @return [String]
+        def create_mutation
+          <<~GRAPHQL
+            mutation($input: CreateProjectV2Input!) {
+              createProjectV2(input: $input) {
+                projectV2 {
+                  id
+                  number
+                }
+              }
+            }
+          GRAPHQL
+        end
+
+        # @return [String]
+        def update_mutation
+          <<~GRAPHQL
+            mutation($input: UpdateProjectV2Input!) {
+              updateProjectV2(input: $input) {
+                projectV2 {
+                  id
+                  number
+                }
+              }
+            }
+          GRAPHQL
+        end
     end
 
     # @see super
@@ -411,6 +556,11 @@ module PlanMyStuff
       @id = attrs.delete(:id)
       @number = attrs.delete(:number)
       @closed = attrs.delete(:closed)
+      @metadata = PlanMyStuff::ProjectMetadata.new
+      @raw_readme = nil
+      @readme = nil
+      @description = nil
+      @updated_at = nil
       super
       @statuses ||= []
       @fields ||= []
@@ -431,6 +581,58 @@ module PlanMyStuff
       field
     end
 
+    # @return [Boolean]
+    def pms_project?
+      metadata.schema_version.present?
+    end
+
+    # Persists the project. Creates if new, updates if persisted.
+    #
+    # @raise [PlanMyStuff::StaleObjectError] on update if stale
+    #
+    # @return [self]
+    #
+    def save!
+      if new_record?
+        created = self.class.create!(title: title, readme: readme || '')
+        hydrate_from_project(created)
+      else
+        update!(title: title, readme: readme)
+      end
+
+      self
+    end
+
+    # 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)
+      raise_if_stale!
+
+      self.class.update!(
+        project_number: number,
+        **attrs,
+      )
+
+      reload
+    end
+
+    # Re-fetches this project from GitHub and updates all local attributes.
+    #
+    # @return [self]
+    #
+    def reload
+      fresh = self.class.find(number)
+      hydrate_from_project(fresh)
+      self
+    end
+
     private
 
       # Populates this instance from a list query node (summary only).
@@ -443,8 +645,10 @@ module PlanMyStuff
         @id = node[:id]
         @number = node[:number]
         @title = node[:title]
+        @description = node[:shortDescription]
         @url = node[:url]
         @closed = node[:closed]
+        @updated_at = parse_github_time(node[:updatedAt])
         @persisted = true
       end
 
@@ -461,8 +665,15 @@ module PlanMyStuff
         @id = graphql_project[:id]
         @number = graphql_project[:number]
         @title = graphql_project[:title]
+        @description = graphql_project[:shortDescription]
         @url = graphql_project[:url]
         @closed = graphql_project[:closed]
+        @updated_at = parse_github_time(graphql_project[:updatedAt])
+
+        @raw_readme = graphql_project[:readme] || ''
+        parsed = PlanMyStuff::MetadataParser.parse(@raw_readme)
+        @metadata = PlanMyStuff::ProjectMetadata.from_hash(parsed[:metadata])
+        @readme = parsed[:body]
 
         fields_nodes = graphql_project.dig(:fields, :nodes) || []
         @statuses = extract_statuses(fields_nodes)
@@ -473,6 +684,56 @@ module PlanMyStuff
         @persisted = true
       end
 
+      # Copies attributes from another Project instance into self.
+      #
+      # @param other [PlanMyStuff::Project]
+      #
+      # @return [void]
+      #
+      def hydrate_from_project(other)
+        @id = other.id
+        @number = other.number
+        @title = other.title
+        @description = other.description
+        @url = other.url
+        @closed = other.closed
+        @updated_at = other.updated_at
+        @raw_readme = other.raw_readme
+        @readme = other.readme
+        @metadata = other.metadata
+        @statuses = other.statuses
+        @fields = other.fields
+        @items = other.items
+        @next_cursor = other.next_cursor
+        @has_next_page = other.has_next_page
+        @persisted = true
+      end
+
+      # Raises StaleObjectError if the remote project has been modified
+      # since this instance was loaded.
+      #
+      # @raise [PlanMyStuff::StaleObjectError]
+      #
+      # @return [void]
+      #
+      def raise_if_stale!
+        return if new_record?
+        return if updated_at.nil?
+
+        remote = self.class.find(number)
+        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
+
+        raise(PlanMyStuff::StaleObjectError.new(
+          "Project ##{number} has been modified remotely",
+          local_updated_at: local_time,
+          remote_updated_at: remote_time,
+        ))
+      end
+
       # Extracts status options from the "Status" single-select field.
       #
       # @param fields_nodes [Array<Hash>]

data/lib/plan_my_stuff/project_item.rb

@@ -29,6 +29,8 @@ module PlanMyStuff
     attr_accessor :number
     # @return [String, nil]
     attr_accessor :url
+    # @return [PlanMyStuff::Repo, nil]
+    attr_accessor :repo
     # @return [String, nil]
     attr_accessor :state
     # @return [String, nil]
@@ -38,7 +40,7 @@ module PlanMyStuff
     # @return [PlanMyStuff::Project, nil]
     attr_accessor :project
     # @return [PlanMyStuff::Issue, nil] linked issue (nil for draft items)
-    attr_accessor :issue
+    attr_writer :issue
 
     class << self
       # Builds a persisted ProjectItem from parsed item data.
@@ -56,6 +58,7 @@ module PlanMyStuff
           title: item_hash[:title],
           number: item_hash[:number],
           url: item_hash[:url],
+          repo: item_hash[:repo],
           state: item_hash[:state],
           status: item_hash[:status],
           field_values: item_hash[:field_values] || {},
@@ -170,6 +173,7 @@ module PlanMyStuff
           item = build(
             {
               id: item_data[:id],
+              content_node_id: node_id,
               title: issue.title,
               number: issue.number,
               url: nil,
@@ -210,6 +214,8 @@ module PlanMyStuff
           build(
             {
               id: item_data[:id],
+              content_node_id: item_data.dig(:content, :id),
+              type: 'DRAFT_ISSUE',
               title: title,
               number: nil,
               url: nil,
@@ -221,17 +227,9 @@ module PlanMyStuff
           )
         end
 
-        # Resolves a project number, falling back to config.default_project_number.
-        #
-        # @param project_number [Integer, nil]
-        #
-        # @return [Integer]
-        #
+        # @see PlanMyStuff::Project.resolve_default_project_number
         def resolve_default_project_number(project_number)
-          return project_number if project_number.present?
-
-          PlanMyStuff.configuration.default_project_number ||
-            raise(ArgumentError, 'project_number is required when config.default_project_number is not set')
+          PlanMyStuff::Project.resolve_default_project_number(project_number)
         end
 
         # @return [String]
@@ -261,6 +259,7 @@ module PlanMyStuff
               }) {
                 projectItem {
                   id
+                  content { ... on DraftIssue { id } }
                 }
               }
             }
@@ -393,6 +392,7 @@ module PlanMyStuff
         content_node_id: content_node_id,
         assignees: Array.wrap(assignees),
         draft: draft?,
+        repo: repo,
       )
     end
 
@@ -401,6 +401,14 @@ module PlanMyStuff
       type == 'DRAFT_ISSUE'
     end
 
+    # @return [PlanMyStuff::Issue, nil]
+    def issue
+      return @issue if defined?(@issue)
+      return if draft?
+
+      @issue = PMS::Issue.find(number, repo: repo)
+    end
+
     private
 
       # Marks this record as persisted.

data/lib/plan_my_stuff/project_metadata.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class ProjectMetadata < BaseMetadata
+    class << self
+      # Builds a ProjectMetadata from a parsed hash (e.g. from MetadataParser)
+      #
+      # @param hash [Hash]
+      #
+      # @return [PlanMyStuff::ProjectMetadata]
+      #
+      def from_hash(hash)
+        metadata = new
+        apply_common_from_hash(metadata, hash, PlanMyStuff.configuration.custom_fields_for(:project))
+
+        metadata
+      end
+
+      # Builds a new ProjectMetadata for project 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
+      #
+      # @return [PlanMyStuff::ProjectMetadata]
+      #
+      def build(user:, visibility: 'internal', custom_fields: {})
+        metadata = new
+        apply_common_build(
+          metadata,
+          user: user,
+          visibility: visibility,
+          custom_fields_data: custom_fields,
+          custom_fields_schema: PlanMyStuff.configuration.custom_fields_for(:project),
+        )
+
+        metadata
+      end
+    end
+  end
+end

data/lib/plan_my_stuff/repo.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class Repo
+    # @return [Symbol, nil] configured key (e.g. :my_repo)
+    attr_reader :key
+
+    # @return [String] repo name (e.g. "MyRepository")
+    attr_reader :name
+
+    # @return [String] organization name (e.g. "YourOrgName")
+    attr_reader :organization
+
+    delegate :split, to: :to_s
+
+    class << self
+      # Builds a Repo instance from a Symbol key, full name String, or nil (default).
+      #
+      # @param repo [Symbol, String, PlanMyStuff::Repo, nil]
+      #
+      # @return [PlanMyStuff::Repo]
+      #
+      def resolve(repo = nil)
+        return repo if repo.is_a?(PlanMyStuff::Repo)
+
+        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
+          full_name = PlanMyStuff.configuration.repos[repo]
+          raise(ArgumentError, "Unknown repo key: #{repo.inspect}") if full_name.nil?
+
+          from_full_name(full_name, key: repo)
+        when String
+          key = PlanMyStuff.configuration.repos.key(repo)
+          from_full_name(repo, key: key)
+        else
+          raise(ArgumentError, "Cannot resolve repo: #{repo.inspect}")
+        end
+      end
+
+      private
+
+        # @param full_name [String] e.g. "YourOrgName/MyRepository"
+        # @param key [Symbol, nil]
+        #
+        # @return [PlanMyStuff::Repo]
+        #
+        def from_full_name(full_name, key: nil)
+          org, name = full_name.split('/', 2)
+
+          raise(ArgumentError, "Invalid repo full_name: #{full_name.inspect}") if name.nil?
+
+          new(name: name, organization: org, key: key)
+        end
+    end
+
+    # @param name [String]
+    # @param organization [String]
+    # @param key [Symbol, nil]
+    #
+    def initialize(name:, organization:, key: nil)
+      @key = key
+      @name = name
+      @organization = organization
+    end
+
+    # @return [String] full repo path (e.g. "YourOrgName/MyRepository")
+    def full_name
+      "#{organization}/#{name}"
+    end
+
+    # @see #full_name
+    alias to_s full_name
+
+    # Enables implicit string coercion so Repo instances behave as
+    # strings when passed to Octokit or compared with String#==.
+    #
+    # @see #full_name
+    alias to_str full_name
+
+    # Compares by full_name. Accepts another Repo or a String.
+    #
+    # @param other [PlanMyStuff::Repo, String, Object]
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      case other
+      when PlanMyStuff::Repo
+        full_name == other.full_name
+      when String
+        full_name == other
+      else
+        super
+      end
+    end
+  end
+end

data/lib/plan_my_stuff/test_helpers.rb

@@ -316,10 +316,17 @@ module PlanMyStuff
             },
           }
 
+          resolved_repo =
+            if params[:repo]
+              PlanMyStuff::Repo.resolve(params[:repo]).full_name
+            else
+              'TestOrg/TestRepo'
+            end
+
           PlanMyStuff::TestHelpers.build_issue(
             title: params[:title],
             body: params[:body],
-            repo: params[:repo]&.to_s || 'TestOrg/TestRepo',
+            repo: resolved_repo,
             labels: params[:labels] || [],
           )
         end
@@ -330,7 +337,8 @@ module PlanMyStuff
             params: { number: number, repo: repo },
           }
 
-          PlanMyStuff::TestHelpers.build_issue(number: number, repo: repo&.to_s || 'TestOrg/TestRepo')
+          resolved_repo = repo ? PlanMyStuff::Repo.resolve(repo).full_name : 'TestOrg/TestRepo'
+          PlanMyStuff::TestHelpers.build_issue(number: number, repo: resolved_repo)
         end
 
         issue_mod.define_singleton_method(:list) do |**params|

data/lib/plan_my_stuff/version.rb

@@ -3,8 +3,8 @@
 module PlanMyStuff
   module VERSION
     MAJOR = 0
-    MINOR = 1
-    TINY = 1
+    MINOR = 3
+    TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)
     PRE = nil