plan_my_stuff 0.3.0 → 0.4.0

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

@@ -1,6 +1,11 @@
 <h1><%= @project.title %></h1>
 
-<p><%= link_to('Edit', plan_my_stuff.edit_project_path(@project.number)) %></p>
+<p>
+  <%= link_to('Edit', plan_my_stuff.edit_project_path(@project.number)) %>
+  <% if @support_user && @project.url.present? %>
+    <%= link_to('View on GitHub', @project.url, target: '_blank', rel: 'noopener') %>
+  <% end %>
+</p>
 
 <% if @statuses.any? %>
   <table>
@@ -29,7 +34,7 @@
 
                 <%=
                   form_with(
-                    url: plan_my_stuff.move_project_item_path(@project.number, item.id),
+                    url: plan_my_stuff.project_item_status_path(@project.number, item.id),
                     method: :patch,
                     local: true,
                   ) do |form|
@@ -45,8 +50,8 @@
                         <%= username %>
                         <%=
                           form_with(
-                            url: plan_my_stuff.unassign_project_item_path(@project.number, item.id),
-                            method: :patch,
+                            url: plan_my_stuff.project_item_assignment_path(@project.number, item.id),
+                            method: :delete,
                             local: true,
                             html: { style: 'display: inline' },
                           ) do |form|
@@ -61,7 +66,7 @@
 
                 <%=
                   form_with(
-                    url: plan_my_stuff.assign_project_item_path(@project.number, item.id),
+                    url: plan_my_stuff.project_item_assignment_path(@project.number, item.id),
                     method: :patch,
                     local: true,
                   ) do |form|

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

@@ -0,0 +1,12 @@
+<h1>Add Item to <%= @project.title %></h1>
+
+<% if flash[:error].present? %>
+  <p style="color: red;"><%= flash[:error] %></p>
+<% end %>
+
+<%=
+  render({
+    partial: 'plan_my_stuff/testing_projects/partials/items/form',
+    locals: { project: @project },
+  })
+%>

data/app/views/plan_my_stuff/testing_project_items/results/new.html.erb

@@ -0,0 +1,22 @@
+<h1>Fail Item</h1>
+
+<% if flash[:error].present? %>
+  <p style="color: red;"><%= flash[:error] %></p>
+<% end %>
+
+<%= form_with(
+  url: plan_my_stuff.testing_project_item_result_path(@project_number, @item_id),
+  method: :post,
+  local: true,
+) do |form| %>
+  <%= form.hidden_field(:result, value: 'fail') %>
+
+  <div>
+    <%= form.label(:result_notes, 'Result Notes') %>
+    <%= form.text_area(:result_notes, rows: 5, required: true) %>
+  </div>
+
+  <div>
+    <%= form.submit('Submit Failure') %>
+  </div>
+<% end %>

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

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

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

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

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

@@ -0,0 +1,39 @@
+<%
+  persisted = project.persisted?
+  url =
+    if persisted
+      plan_my_stuff.testing_project_path(project.number)
+    else
+      plan_my_stuff.testing_projects_path
+    end
+%>
+<%= form_with(url: url, method: persisted ? :patch : :post, scope: :testing_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(:subject_urls, 'Subject URLs (one per line)') %>
+    <%= form.text_area(:subject_urls, rows: 4, value: project.metadata.subject_urls.join("\n")) %>
+  </div>
+
+  <div>
+    <%= form.label(:due_date, 'Due Date') %>
+    <%= form.date_field(:due_date, value: project.metadata.due_date) %>
+  </div>
+
+  <div>
+    <%= form.label(:deadline_miss_reason, 'Deadline Miss Reason') %>
+    <%= form.text_field(:deadline_miss_reason, value: project.metadata.deadline_miss_reason) %>
+  </div>
+
+  <div>
+    <%= form.submit(persisted ? 'Update Testing Project' : 'Create Testing Project') %>
+  </div>
+<% end %>

data/app/views/plan_my_stuff/testing_projects/partials/_item.html.erb

@@ -0,0 +1,51 @@
+<div style="border: 1px solid black; margin: 1em; padding: 0.5em">
+  <% if item.draft? %>
+    <strong><%= item.title %></strong>
+  <% else %>
+    <strong><%= link_to(item.title, plan_my_stuff.issue_path(item.number, repo: item.repo.full_name)) %></strong>
+    <small>#<%= item.number %></small>
+  <% end %>
+
+  <%=
+    form_with(
+      url: plan_my_stuff.testing_project_item_status_path(project.number, item.id),
+      method: :patch,
+      local: true,
+    ) do |form|
+  %>
+    <%= form.select(:status, statuses, { selected: item.status }, { onchange: 'this.form.requestSubmit();' }) %>
+  <% end %>
+
+  <% if item.field_values['Testers'].present? %>
+    <div><strong>Testers:</strong> <%= item.field_values['Testers'] %></div>
+  <% end %>
+
+  <% if item.field_values['Watchers'].present? %>
+    <div><strong>Watchers:</strong> <%= item.field_values['Watchers'] %></div>
+  <% end %>
+
+  <% if item.field_values['Due Date'].present? %>
+    <div><strong>Due:</strong> <%= item.field_values['Due Date'] %></div>
+  <% end %>
+
+  <% if item.field_values['Result Notes'].present? %>
+    <div><strong>Notes:</strong> <%= item.field_values['Result Notes'] %></div>
+  <% end %>
+
+  <% if item.field_values['Passed At'].present? %>
+    <div><strong>Passed at:</strong> <%= item.field_values['Passed At'] %></div>
+  <% end %>
+
+  <div>
+    <%=
+      button_to(
+        'Pass',
+        plan_my_stuff.testing_project_item_result_path(project.number, item.id),
+        method: :post,
+        params: { result: 'pass' },
+      )
+    %>
+
+    <%= link_to('Fail', plan_my_stuff.new_testing_project_item_result_path(project.number, item.id)) %>
+  </div>
+</div>

data/app/views/plan_my_stuff/testing_projects/partials/items/_form.html.erb

@@ -0,0 +1,35 @@
+<%= form_with(url: plan_my_stuff.testing_project_items_path(project.number), method: :post, local: true) do |form| %>
+  <div>
+    <%= form.label(:title, 'Title') %>
+    <%= form.text_field(:title, required: true) %>
+  </div>
+
+  <div>
+    <%= form.label(:body, 'Body') %>
+    <%= form.text_area(:body, rows: 4) %>
+  </div>
+
+  <div>
+    <%= form.label(:testers, 'Testers (user ids, comma separated)') %>
+    <%= form.text_field(:testers) %>
+  </div>
+
+  <div>
+    <%= form.label(:watchers, 'Watchers (user ids, comma separated)') %>
+    <%= form.text_field(:watchers) %>
+  </div>
+
+  <div>
+    <%= form.label(:pass_mode, 'Pass Mode') %>
+    <%= form.select(:pass_mode, [['All testers must pass', 'all'], ['Any tester can pass', 'any']], { selected: 'all' }) %>
+  </div>
+
+  <div>
+    <%= form.label(:due_date, 'Due Date') %>
+    <%= form.date_field(:due_date) %>
+  </div>
+
+  <div>
+    <%= form.submit('Add Item') %>
+  </div>
+<% end %>

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

@@ -0,0 +1,65 @@
+<h1><%= @project.title %></h1>
+
+<p>
+  <%= link_to('Edit', plan_my_stuff.edit_testing_project_path(@project.number)) %>
+  <% if @support_user && @project.url.present? %>
+    <%= link_to('View on GitHub', @project.url, target: '_blank', rel: 'noopener') %>
+  <% end %>
+</p>
+
+<% if @support_user && @project.metadata.subject_urls.any? %>
+  <p>
+    <strong>Subject URLs:</strong>
+    <% @project.metadata.subject_urls.each do |url| %>
+      <%= link_to(url, url, target: '_blank', rel: 'noopener') %>
+    <% end %>
+  </p>
+<% end %>
+
+<% if @project.metadata.due_date.present? %>
+  <p><strong>Due:</strong> <%= @project.metadata.due_date %></p>
+<% end %>
+
+<% if @statuses.any? %>
+  <table>
+    <thead>
+      <tr>
+        <% @statuses.each do |status| %>
+          <th><%= status %></th>
+        <% end %>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <% @statuses.each do |status| %>
+          <td>
+            <% items = @items_by_status[status] || [] %>
+            <% items.each do |item| %>
+              <%= render({
+                partial: 'plan_my_stuff/testing_projects/partials/item',
+                locals: { item: item, project: @project, statuses: @statuses },
+              }) %>
+            <% end %>
+            <% if items.empty? %>
+              <em>No items</em>
+            <% end %>
+          </td>
+        <% end %>
+      </tr>
+    </tbody>
+  </table>
+<% else %>
+  <p>No statuses configured for this project.</p>
+<% end %>
+
+<h2>Add Item</h2>
+
+<p><%= link_to('Add item with details', plan_my_stuff.new_testing_project_item_path(@project.number)) %></p>
+
+<%= form_with(url: plan_my_stuff.testing_project_items_path(@project.number), method: :post, local: true) do |form| %>
+  <%= form.label(:title, 'Title') %>
+  <%= form.text_field(:title, required: true) %>
+  <%= form.label(:body, 'Body') %>
+  <%= form.text_area(:body) %>
+  <%= form.submit('Add Item') %>
+<% end %>

data/config/routes.rb

@@ -1,24 +1,47 @@
 # frozen_string_literal: true
 
 PlanMyStuff::Engine.routes.draw do
-  resources :issues, except: %i[destroy] do
-    member do
-      patch :close
-      patch :reopen
-      post :add_viewers
-      delete :remove_viewer
+  config = PlanMyStuff.configuration
+  mount_groups = config.mount_groups
+
+  if mount_groups.fetch(:issues, true)
+    resources :issues, except: %i[destroy], controller: config.controller_for(:issues) do
+      resource :closure, only: %i[create destroy], controller: config.controller_for(:'issues/closures')
+      resource :waiting, only: %i[create destroy], controller: config.controller_for(:'issues/waitings')
+      resources :viewers, only: %i[create destroy], controller: config.controller_for(:'issues/viewers')
+      if config.pipeline_enabled
+        resource(
+          :take,
+          only: :create,
+          controller: config.controller_for(:'issues/takes'),
+        )
+      end
+      resources :comments, only: %i[create edit update], controller: config.controller_for(:comments)
+      resources :labels, only: %i[create destroy], controller: config.controller_for(:labels)
+      resources :links, only: %i[create destroy], controller: config.controller_for(:'issues/links')
+      resources :approvals, only: %i[create update destroy], controller: config.controller_for(:'issues/approvals')
+    end
+  end
+
+  if mount_groups.fetch(:webhooks, true) && config.pipeline_enabled
+    namespace :webhooks do
+      resource :github, only: %i[create], controller: config.controller_for(:'webhooks/github')
+      resource :aws, only: %i[create], controller: config.controller_for(:'webhooks/aws')
     end
-    resources :comments, only: %i[create edit update]
-    post 'labels', to: 'labels#add_to_issue', as: :add_label
-    delete 'labels/:name', to: 'labels#remove_from_issue', as: :remove_label
   end
 
-  resources :projects, except: %i[destroy] do
-    resources :items, only: %i[create], controller: 'project_items' do
-      member do
-        patch :move
-        patch :assign
-        patch :unassign
+  if mount_groups.fetch(:projects, true)
+    resources :projects, except: %i[destroy], controller: config.controller_for(:projects) do
+      resources :items, only: %i[create], controller: config.controller_for(:project_items) do
+        resource :status, only: %i[update], controller: config.controller_for(:'project_items/statuses')
+        resource :assignment, only: %i[update destroy], controller: config.controller_for(:'project_items/assignments')
+      end
+    end
+
+    resources :testing_projects, except: %i[destroy index], controller: config.controller_for(:testing_projects) do
+      resources :items, only: %i[new create], controller: config.controller_for(:testing_project_items) do
+        resource :status, only: %i[update], controller: config.controller_for(:'project_items/statuses')
+        resource :result, only: %i[new create], controller: config.controller_for(:'testing_project_items/results')
       end
     end
   end

data/lib/generators/plan_my_stuff/install/templates/initializer.rb

@@ -26,6 +26,13 @@ PMS.configure do |config|
   # Default GitHub Projects V2 number for add_to_project calls.
   # config.default_project_number = 14
 
+  # Template project to clone when creating new Testing Projects.
+  # When set, TestingProject.create! copies this project (preserving its
+  # custom fields and board layout) instead of bootstrapping fields from scratch.
+  # The template should be a pre-configured testing project with the correct
+  # fields and board view already set up in the GitHub UI.
+  # config.testing_template_project_number = 42
+
   # --------------------------------------------------------------------------
   # App identity
   # --------------------------------------------------------------------------
@@ -85,11 +92,9 @@ PMS.configure do |config|
   #   update_status:  'PmsUpdateStatusJob'
   # }
 
-  # Custom notifier for deferred requests (proc/class), or nil to use
-  # the built-in DeferredMailer.
-  # config.deferred_notifier = nil
-  # config.deferred_email_from = 'noreply@example.com'
-  # config.deferred_email_to = 'it-support@example.com'
+  # Fallback actor for notification events (plan_my_stuff.*) when a caller
+  # does not pass an explicit user: kwarg. Proc/lambda called at event time.
+  # config.current_user = -> { Current.user }
 
   # --------------------------------------------------------------------------
   # Custom fields
@@ -112,4 +117,132 @@ PMS.configure do |config|
 
   # Comment-only fields (merged on top of shared, context wins on conflicts):
   # config.comment_custom_fields = {}
+
+  # --------------------------------------------------------------------------
+  # Release pipeline
+  # --------------------------------------------------------------------------
+  # config.pipeline_enabled = true
+  # config.pipeline_project_number = 14
+
+  # GitHub webhook HMAC-SHA256 secret (required when webhook routes are mounted).
+  # config.webhook_secret = Rails.application.credentials.dig(:plan_my_stuff, :webhook_secret)
+
+  # Configurable display aliases for pipeline statuses.
+  # config.pipeline_statuses = {
+  #   'Submitted' => 'Triaged',
+  #   'Completed' => 'Done',
+  # }
+
+  # config.main_branch = 'main'
+  # config.production_branch = 'production'
+
+  # --------------------------------------------------------------------------
+  # Follow-up reminders
+  # --------------------------------------------------------------------------
+  # Daily sweep that fires `plan_my_stuff.issue.reminder_due` events on
+  # waiting issues and auto-closes issues that exceed the inactivity
+  # ceiling. Consuming app is responsible for the initial enqueue:
+  #
+  #   # Enqueue one sweep job per configured repo:
+  #   rake plan_my_stuff:reminders:sweep
+  #
+  #   # Or a single repo:
+  #   rake plan_my_stuff:reminders:sweep REPO=element
+  #
+  # Each job self-requeues after perform (default: 6:30am ET next day);
+  # running the rake task once on app boot is enough. Override
+  # `RemindersSweepJob.next_run` on a subclass to change the cadence.
+  #
+  # config.reminders_enabled = true
+  #
+  # Days-since-waiting at which reminders fire. Per-issue override via
+  # `issue.metadata.reminder_days = [...]`.
+  # config.reminder_days = [1, 3, 7, 10, 14, 18]
+  #
+  # Days of continuous waiting before the sweep auto-closes the issue
+  # (emits `issue.closed_inactive` instead of the regular `issue.closed`).
+  # config.inactivity_close_days = 30
+  #
+  # Label names the gem creates and manages on waiting/inactive issues.
+  # config.waiting_on_user_label = 'waiting-on-user'
+  # config.waiting_on_approval_label = 'waiting-on-approval'
+  # config.user_inactive_label = 'user-inactive'
+
+  # --------------------------------------------------------------------------
+  # Auto-archiving of aged-closed issues
+  # --------------------------------------------------------------------------
+  # Piggybacks the RemindersSweepJob. For every issue closed more than
+  # `archive_closed_after_days` ago (based on GitHub's `closed_at`) the
+  # sweep: adds the configured label, locks the conversation, removes
+  # the issue from every Projects V2 board, stamps `metadata.archived_at`,
+  # and emits `plan_my_stuff.issue.archived` with `reason: :aged_closed`.
+  # Issues auto-closed by the inactivity sweep (closed_by_inactivity) are
+  # excluded. Non-PMS issues are excluded.
+  #
+  # config.archiving_enabled = true
+  # config.archive_closed_after_days = 90
+  # config.archived_label = 'archived'
+
+  # --------------------------------------------------------------------------
+  # AWS webhook (ECS deployments via SNS)
+  # --------------------------------------------------------------------------
+  # Expected SNS topic ARN for webhook validation.
+  # config.sns_topic_arn = 'arn:aws:sns:us-east-1:123456:ecs-deploy-topic'
+
+  # ECS service identifier - suffix matched against resource ARNs in events.
+  # config.aws_service_identifier = 'myapp-production-web'
+
+  # Commit hash of the currently deploying build. Prefix-matched against
+  # issue metadata commit_sha on SERVICE_DEPLOYMENT_COMPLETED events.
+  # config.production_commit_sha = Rails.configuration.x.image_tag
+
+  # Toggle for processing AWS webhook events (default: Rails.env.production?).
+  # config.process_aws_webhooks = Rails.env.production?
+
+  # SNS signature verifier (default: Aws::SNS::MessageVerifier). Must respond
+  # to authenticate!(raw_body). Provide aws-sdk-sns in your Gemfile.
+  # config.sns_verifier_class = Aws::SNS::MessageVerifier
+  # config.sns_verifier_error = Aws::SNS::MessageVerifier::VerificationError
+
+  # --------------------------------------------------------------------------
+  # Route mounting
+  # --------------------------------------------------------------------------
+  # Per-group toggles for which engine route groups to mount.
+  # config.mount_groups = { webhooks: true, issues: true, projects: true }
+
+  # --------------------------------------------------------------------------
+  # Controller overrides (Devise-style)
+  # --------------------------------------------------------------------------
+  # Swap in your own controller for any mounted route group. Typical use is
+  # to subclass the gem controller and slot the subclass in here:
+  #
+  #   # app/controllers/issues_controller.rb
+  #   class IssuesController < PlanMyStuff::IssuesController
+  #     before_action :require_admin
+  #   end
+  #
+  #   # config/initializers/plan_my_stuff.rb
+  #   config.controllers = { issues: 'issues' }
+  #
+  # Unset keys fall back to the gem default.
+  #
+  # Controllable keys (with gem defaults):
+  #   :issues                           => 'plan_my_stuff/issues'
+  #   :comments                         => 'plan_my_stuff/comments'
+  #   :labels                           => 'plan_my_stuff/labels'
+  #   :projects                         => 'plan_my_stuff/projects'
+  #   :project_items                    => 'plan_my_stuff/project_items'
+  #   :testing_projects                 => 'plan_my_stuff/testing_projects'
+  #   :testing_project_items            => 'plan_my_stuff/testing_project_items'
+  #   :'issues/closures'                => 'plan_my_stuff/issues/closures'
+  #   :'issues/viewers'                 => 'plan_my_stuff/issues/viewers'
+  #   :'issues/takes'                   => 'plan_my_stuff/issues/takes'
+  #   :'issues/waitings'                => 'plan_my_stuff/issues/waitings'
+  #   :'issues/links'                   => 'plan_my_stuff/issues/links'
+  #   :'issues/approvals'               => 'plan_my_stuff/issues/approvals'
+  #   :'project_items/statuses'         => 'plan_my_stuff/project_items/statuses'
+  #   :'project_items/assignments'      => 'plan_my_stuff/project_items/assignments'
+  #   :'testing_project_items/results'  => 'plan_my_stuff/testing_project_items/results'
+  #   :'webhooks/github'                => 'plan_my_stuff/webhooks/github'
+  #   :'webhooks/aws'                   => 'plan_my_stuff/webhooks/aws'
 end

data/lib/plan_my_stuff/application_record.rb

@@ -7,6 +7,13 @@ module PlanMyStuff
   # Provides shared persistence predicates and utility helpers.
   class ApplicationRecord
     include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Dirty
+    include ActiveModel::Serializers::JSON
+
+    # @return [Object, nil] raw GitHub API response this record was hydrated from.
+    #   Escape hatch for consuming apps to access fields the gem doesn't expose.
+    attr_reader :github_response
 
     class << self
       # Reads a field from an object that may respond to method calls or hash access.
@@ -19,11 +26,96 @@ module PlanMyStuff
       def read_field(obj, field)
         obj.respond_to?(field) ? obj.public_send(field) : obj[field]
       end
+
+      private
+
+        # @param client [PlanMyStuff::Client]
+        #
+        # @return [Boolean]
+        #
+        def not_modified?(client)
+          response = client.last_response
+          return false if response.nil?
+
+          response.status == 304
+        end
+
+        # Captures the +ETag+ header from the most recent REST response and
+        # forwards it to +cache_writer+.
+        #
+        # @param client [PlanMyStuff::Client]
+        # @param repo [String]
+        # @param id [Integer, nil]
+        # @param body [Object] parsed GitHub response
+        # @param cache_writer [Symbol] +PlanMyStuff::Cache+ method name, e.g. +:write_issue+
+        #
+        # @return [void]
+        #
+        def store_etag_to_cache(client, repo, id, body, cache_writer:)
+          return if id.nil?
+
+          response = client.last_response
+          return if response.nil?
+
+          etag = response.headers && response.headers['etag']
+          return if etag.blank?
+
+          PlanMyStuff::Cache.public_send(cache_writer, repo, id, etag: etag, body: body)
+        end
+
+        # Captures the +ETag+ header from the most recent REST response and
+        # forwards it to +Cache.write_list+.
+        #
+        # @param client [PlanMyStuff::Client]
+        # @param resource [Symbol] :issue or :comment
+        # @param repo [String]
+        # @param params [Hash] query params that identify this list
+        # @param body [Object] parsed GitHub list response
+        #
+        # @return [void]
+        #
+        def store_list_etag_to_cache(client, resource, repo, params, body)
+          response = client.last_response
+          return if response.nil?
+
+          etag = response.headers && response.headers['etag']
+          return if etag.blank?
+
+          PlanMyStuff::Cache.write_list(resource, repo, params, etag: etag, body: body)
+        end
+
+        # Reads a REST resource through the ETag cache.
+        #
+        # On a cache hit sends +If-None-Match+; a 304 returns the cached
+        # body. A 200 stores the new ETag via +cache_writer+ and returns
+        # the fresh result.
+        #
+        # @param client [PlanMyStuff::Client]
+        # @param repo [String]
+        # @param id [Integer]
+        # @param rest_method [Symbol] Octokit method name
+        # @param cache_reader [Symbol] +PlanMyStuff::Cache+ method name, e.g. +:read_issue+
+        # @param cache_writer [Symbol] +PlanMyStuff::Cache+ method name, e.g. +:write_issue+
+        #
+        # @return [Object] parsed GitHub response
+        #
+        def fetch_with_etag_cache(client, repo, id, rest_method:, cache_reader:, cache_writer:)
+          cached = PlanMyStuff::Cache.public_send(cache_reader, repo, id)
+          options = cached ? { headers: { 'If-None-Match' => cached[:etag] } } : {}
+
+          result = client.rest(rest_method, repo, id, **options)
+
+          return cached[:body] if cached && not_modified?(client)
+
+          store_etag_to_cache(client, repo, id, result, cache_writer: cache_writer)
+          result
+        end
     end
 
     def initialize(**)
       super
       @persisted = false
+      @destroyed = false
     end
 
     # @return [Boolean]
@@ -36,8 +128,37 @@ module PlanMyStuff
       !@persisted
     end
 
+    # @return [Boolean]
+    def destroyed?
+      @destroyed
+    end
+
     private
 
+      # Marks this record as persisted. Subclasses call this after a
+      # successful create/find/update against the underlying GitHub
+      # resource. Also applies any pending dirty changes so the record
+      # is clean after hydration and +#previous_changes+ reflects the
+      # values that were just loaded.
+      #
+      # @return [void]
+      #
+      def persisted!
+        @persisted = true
+        changes_applied
+      end
+
+      # Marks this record as destroyed. Subclasses call this from their
+      # +destroy!+ implementations after the underlying remote resource
+      # has been deleted.
+      #
+      # @return [void]
+      #
+      def destroyed!
+        @destroyed = true
+        @persisted = false
+      end
+
       # Reads a field from an object that may respond to method calls or hash access.
       #
       # @param obj [Object]