plan_my_stuff 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fdaa17653ccaf192c32d3ba21c5eb0ea4954b2a983d1d0d8f3665a9a792d065
-  data.tar.gz: d61fb2fba100a20b0e2f40744e2e6c4c936ff4d55c2cbbdf428f8f6d30ed4ea8
+  metadata.gz: 9b5b0d6a9e0582853ebf435a48b49fabb8dc9bd1227bddc6f2c3467d74872c80
+  data.tar.gz: 3e1df8e562940c9c1435c2edc4b88c7b85c2c2c8309b95702f8f6d3f978bdf19
 SHA512:
-  metadata.gz: cf7a2e48f07ef85f21725524db9a11bad2d4da8ecf403c1e60a3817a86087d0a06ee98d88d12a2a830584c950c5705ca0693c1c5b8f7fd5229b3ffbc0851174a
-  data.tar.gz: 89bc0e780f36649e7abacefe7b0fa65f56d6302f66cc23c49cfb343d4ec8f1190b58cd8f4e59c2ba52a5ab8d199bf459a9060ea69321d0793d3da34f7a4e5294
+  metadata.gz: fdc842d462d7e04c163560c475bd6519e04b4b5f57b2684be5137ed32ff0bc9e257d9f09e7ab1cda06e6106065e38e4a1c80f0fea96d812841141cc14cbed4a6
+  data.tar.gz: 9e4954b597a281e4c68e1ea9ecbe2748efbcac31062f7fd3b925b887dc0616015df27df8c0122fc4165621227f5eefa13ead1ce0583cbe9dcd377ecaf0e47e23

data/app/controllers/plan_my_stuff/projects_controller.rb

@@ -7,11 +7,65 @@ module PlanMyStuff
       @projects = PMS::Project.list.reject(&:closed)
     end
 
+    # GET /projects/new
+    def new
+      @project = PMS::Project.new
+    end
+
+    # POST /projects
+    def create
+      @project = PMS::Project.create!(
+        title: project_params[:title],
+        readme: project_params[:readme] || '',
+        description: project_params[:description],
+        user: pms_current_user,
+      )
+
+      flash[:success] = 'Project was successfully created.'
+      redirect_to(plan_my_stuff.project_path(@project.number))
+    rescue PMS::ValidationError => e
+      @project = PMS::Project.new(
+        title: project_params[:title],
+        readme: project_params[:readme],
+      )
+      flash.now[:error] = e.message
+      render(:new, status: PMS.unprocessable_status)
+    end
+
     # GET /projects/:id
     def show
       @project = PMS::Project.find(params[:id].to_i)
       @statuses = @project.statuses.pluck(:name)
       @items_by_status = @project.items.group_by(&:status)
     end
+
+    # GET /projects/:id/edit
+    def edit
+      @project = PMS::Project.find(params[:id].to_i)
+    end
+
+    # PATCH/PUT /projects/:id
+    def update
+      @project = PMS::Project.find(params[:id].to_i)
+
+      @project.update!(
+        title: project_params[:title],
+        readme: project_params[:readme],
+        description: project_params[:description],
+      )
+
+      flash[:success] = 'Project was successfully updated.'
+      redirect_to(plan_my_stuff.project_path(@project.number))
+    rescue PMS::StaleObjectError
+      flash.now[:error] = 'Project was modified by someone else. Please review the latest changes and try again.'
+      render(:edit, status: PMS.unprocessable_status)
+    end
+
+    private
+
+      # @return [ActionController::Parameters]
+      def project_params
+        params.require(:project).permit(:title, :readme, :description)
+      end
   end
 end

data/app/views/plan_my_stuff/projects/edit.html.erb

@@ -0,0 +1,7 @@
+<h1>Edit Project #<%= @project.number %></h1>
+
+<% if flash[:error].present? %>
+  <p style="color: red;"><%= flash[:error] %></p>
+<% end %>
+
+<%= render({ partial: 'plan_my_stuff/projects/partials/form', locals: { project: @project } }) %>

data/app/views/plan_my_stuff/projects/index.html.erb

@@ -11,3 +11,5 @@
 <% else %>
   <p>No projects found.</p>
 <% end %>
+
+<p><%= link_to('New Project', plan_my_stuff.new_project_path) %></p>

data/app/views/plan_my_stuff/projects/new.html.erb

@@ -0,0 +1,7 @@
+<h1>New Project</h1>
+
+<% if flash[:error].present? %>
+  <p style="color: red;"><%= flash[:error] %></p>
+<% end %>
+
+<%= render({ partial: 'plan_my_stuff/projects/partials/form', locals: { project: @project } }) %>

data/app/views/plan_my_stuff/projects/partials/_form.html.erb

@@ -0,0 +1,29 @@
+<%
+  persisted = project.persisted?
+  url =
+    if persisted
+      plan_my_stuff.project_path(project.number)
+    else
+      plan_my_stuff.projects_path
+    end
+%>
+<%= form_with(url: url, method: persisted ? :patch : :post, scope: :project) do |form| %>
+  <div>
+    <%= form.label(:title, 'Title') %>
+    <%= form.text_field(:title, value: project.title, required: true) %>
+  </div>
+
+  <div>
+    <%= form.label(:description, 'Description') %>
+    <%= form.text_field(:description, value: project.description) %>
+  </div>
+
+  <div>
+    <%= form.label(:readme, 'Readme') %>
+    <%= form.text_area(:readme, rows: 8, value: project.readme) %>
+  </div>
+
+  <div>
+    <%= form.submit(persisted ? 'Update Project' : 'Create Project') %>
+  </div>
+<% end %>

data/app/views/plan_my_stuff/projects/show.html.erb

@@ -1,5 +1,7 @@
 <h1><%= @project.title %></h1>
 
+<p><%= link_to('Edit', plan_my_stuff.edit_project_path(@project.number)) %></p>
+
 <% if @statuses.any? %>
   <table>
     <thead>

data/config/routes.rb

@@ -13,7 +13,7 @@ PlanMyStuff::Engine.routes.draw do
     delete 'labels/:name', to: 'labels#remove_from_issue', as: :remove_label
   end
 
-  resources :projects, only: %i[index show] do
+  resources :projects, except: %i[destroy] do
     resources :items, only: %i[create], controller: 'project_items' do
       member do
         patch :move

data/lib/plan_my_stuff/application_record.rb

@@ -48,5 +48,28 @@ module PlanMyStuff
       def read_field(obj, field)
         self.class.read_field(obj, field)
       end
+
+      # Reads a field from an object, returning nil if the field does not exist.
+      #
+      # @param obj [Object]
+      # @param field [Symbol]
+      #
+      # @return [Object, nil]
+      #
+      def safe_read_field(obj, field)
+        read_field(obj, field)
+      rescue NameError
+        nil
+      end
+
+      # @return [Time, nil]
+      def parse_github_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
 end

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"
@@ -42,8 +38,6 @@ module PlanMyStuff
           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(
@@ -70,14 +64,11 @@ module PlanMyStuff
           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
@@ -110,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,

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
 
@@ -224,7 +226,6 @@ module PlanMyStuff
       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)
@@ -318,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)
@@ -337,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
@@ -352,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/configuration.rb

@@ -92,12 +92,51 @@ module PlanMyStuff
     #
     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}]
@@ -117,6 +156,12 @@ module PlanMyStuff
       @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.
@@ -162,6 +207,7 @@ module PlanMyStuff
         case context
         when :issue then issue_custom_fields
         when :comment then comment_custom_fields
+        when :project then project_custom_fields
         else {}
         end
 

data/lib/plan_my_stuff/issue.rb

@@ -24,6 +24,8 @@ module PlanMyStuff
     attr_accessor :state
     # @return [Array<String>] label names
     attr_accessor :labels
+    # @return [Time, nil] GitHub's updated_at timestamp
+    attr_reader :updated_at
     # @return [PlanMyStuff::Repo, nil]
     attr_reader :repo
 
@@ -126,7 +128,6 @@ module PlanMyStuff
             merged_custom_fields,
           ).validate!
 
-          existing_metadata[:updated_at] = Time.now.utc.iso8601
           options[:body] = MetadataParser.serialize(existing_metadata, '')
         end
 
@@ -250,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)
@@ -412,6 +412,7 @@ 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)
         self.repo = repo
 
@@ -434,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
@@ -450,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/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.
@@ -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 {
@@ -408,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
@@ -415,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 ||= []
@@ -435,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).
@@ -447,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
 
@@ -465,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)
@@ -477,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_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/version.rb

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

data/lib/plan_my_stuff.rb

@@ -19,6 +19,7 @@ require_relative 'plan_my_stuff/markdown'
 require_relative 'plan_my_stuff/metadata_parser'
 require_relative 'plan_my_stuff/project'
 require_relative 'plan_my_stuff/project_item'
+require_relative 'plan_my_stuff/project_metadata'
 require_relative 'plan_my_stuff/repo'
 require_relative 'plan_my_stuff/user_resolver'
 require_relative 'plan_my_stuff/verifier'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plan_my_stuff
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brands Insurance
@@ -69,7 +69,10 @@ files:
 - app/views/plan_my_stuff/issues/partials/_labels.html.erb
 - app/views/plan_my_stuff/issues/partials/_viewers.html.erb
 - app/views/plan_my_stuff/issues/show.html.erb
+- app/views/plan_my_stuff/projects/edit.html.erb
 - app/views/plan_my_stuff/projects/index.html.erb
+- app/views/plan_my_stuff/projects/new.html.erb
+- app/views/plan_my_stuff/projects/partials/_form.html.erb
 - app/views/plan_my_stuff/projects/show.html.erb
 - config/routes.rb
 - lib/generators/plan_my_stuff/install/install_generator.rb
@@ -92,6 +95,7 @@ files:
 - lib/plan_my_stuff/metadata_parser.rb
 - lib/plan_my_stuff/project.rb
 - lib/plan_my_stuff/project_item.rb
+- lib/plan_my_stuff/project_metadata.rb
 - lib/plan_my_stuff/repo.rb
 - lib/plan_my_stuff/test_helpers.rb
 - lib/plan_my_stuff/user_resolver.rb