plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/application_record.rb

@@ -7,10 +7,115 @@ 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.
+      #
+      # @param obj [Object]
+      # @param field [Symbol]
+      #
+      # @return [Object]
+      #
+      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]
@@ -23,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]
@@ -33,7 +167,30 @@ module PlanMyStuff
       # @return [Object]
       #
       def read_field(obj, field)
-        obj.respond_to?(field) ? obj.public_send(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/approval.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+module PlanMyStuff
+  # Value object representing a single manager approval on an +Issue+.
+  # Persisted in +IssueMetadata#approvals+ and returned from
+  # +Issue.request_approvals!+, +Issue.approve!+, +Issue.reject!+, and
+  # +Issue.revoke_approval!+.
+  #
+  # Mirrors +PlanMyStuff::Link+: +ActiveModel::Attributes+-backed, with
+  # +Serializers::JSON+ for round-trip through the metadata blob.
+  #
+  class Approval
+    STATUSES = %w[pending approved rejected].freeze
+
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Serializers::JSON
+
+    # @return [Integer] app-side user id of the required approver
+    attribute :user_id, :integer
+    # @return [String] +"pending"+, +"approved"+, or +"rejected"+
+    attribute :status, :string, default: 'pending'
+    # @return [DateTime, nil] timestamp when status flipped to +"approved"+
+    attribute :approved_at, :datetime
+    # @return [DateTime, nil] timestamp when status flipped to +"rejected"+
+    attribute :rejected_at, :datetime
+
+    validates :user_id, presence: true, numericality: { greater_than: 0, only_integer: true }
+    validates :status, inclusion: { in: STATUSES }
+
+    # @return [Boolean]
+    def pending?
+      status == 'pending'
+    end
+
+    # @return [Boolean]
+    def approved?
+      status == 'approved'
+    end
+
+    # @return [Boolean]
+    def rejected?
+      status == 'rejected'
+    end
+
+    # Lazy-resolves the app-side user for this approval.
+    # Not memoized -- +PlanMyStuff::UserResolver+ owns caching.
+    #
+    # @return [Object, nil]
+    #
+    def user
+      PlanMyStuff::UserResolver.resolve(user_id)
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        user_id: user_id,
+        status: status,
+        approved_at: PlanMyStuff.format_time(approved_at),
+        rejected_at: PlanMyStuff.format_time(rejected_at),
+      }
+    end
+
+    # Two approvals are equal when they track the same user AND carry the
+    # same status. A pending and an approved record for the same user are
+    # NOT equal -- matters for set arithmetic during state transitions.
+    #
+    # @param other [Object]
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      return false unless other.is_a?(PlanMyStuff::Approval)
+
+      user_id == other.user_id && status == other.status
+    end
+
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [user_id, status].hash
+    end
+  end
+end

data/lib/plan_my_stuff/archive/sweep.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Archive
+    # Walks a single repo's closed issues, archiving those that have
+    # aged past +config.archive_closed_after_days+. Excludes issues
+    # auto-closed by +Reminders::Closer+ (+metadata.closed_by_inactivity+)
+    # and any that are already archived (marker timestamp or label).
+    #
+    # Paginates +Issue.list(state: :closed)+ until either an empty page
+    # or the hard +MAX_PAGES+ cap. GitHub's +list_issues+ returns in
+    # created-desc order, so closed_at is not monotonic across pages;
+    # we can't short-circuit on "this page is all within cutoff." Each
+    # subsequent sweep skips already-archived issues cheaply via
+    # +skip?+, so the steady-state walk is bounded in practice.
+    class Sweep
+      PAGE_SIZE = 50
+      MAX_PAGES = 20
+
+      # @param repo [Symbol, String] repo key or full name
+      # @param now [Time] clock reference
+      #
+      def initialize(repo:, now: Time.now.utc)
+        @repo = repo
+        @now = now.utc
+      end
+
+      # Runs the sweep. No-op when +config.archiving_enabled+ is false.
+      #
+      # @return [void]
+      #
+      def call
+        return unless PlanMyStuff.configuration.archiving_enabled
+
+        (1..MAX_PAGES).each do |page|
+          issues = PlanMyStuff::Issue.list(
+            repo: @repo,
+            state: :closed,
+            page: page,
+            per_page: PAGE_SIZE,
+          )
+
+          break if issues.empty?
+
+          process(issues)
+        end
+      end
+
+      private
+
+        # Per-issue exceptions are swallowed so a single bad archive
+        # doesn't halt the whole sweep.
+        #
+        # @param issues [Array<PlanMyStuff::Issue>]
+        #
+        # @return [void]
+        #
+        def process(issues)
+          issues.each do |issue|
+            next if skip?(issue)
+
+            issue.archive!(now: @now)
+          rescue => e
+            warn("[PlanMyStuff::Archive::Sweep] #{issue.repo}##{issue.number} failed: #{e.class}: #{e.message}")
+          end
+        end
+
+        # @param issue [PlanMyStuff::Issue]
+        #
+        # @return [Boolean]
+        #
+        def skip?(issue)
+          return true unless issue.pms_issue?
+
+          return true if issue.metadata.closed_by_inactivity
+          return true if issue.metadata.archived_at.present?
+          return true if issue.labels.include?(PlanMyStuff.configuration.archived_label)
+          return true if issue.closed_at.nil?
+
+          age_days = (@now - issue.closed_at.utc) / 1.day
+          age_days < PlanMyStuff.configuration.archive_closed_after_days
+        end
+    end
+  end
+end

data/lib/plan_my_stuff/archive.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Auto-archive engine. The +Sweep+ class walks closed issues in a repo
+  # and delegates to +Issue#archive!+ for each issue whose +closed_at+
+  # has aged past +config.archive_closed_after_days+.
+  #
+  # Entry point for the sweep lives in +RemindersSweepJob+; this module
+  # holds the POROs so they can be unit-tested without ActiveJob.
+  module Archive
+  end
+end

data/lib/plan_my_stuff/attachment.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require 'tmpdir'
+
+module PlanMyStuff
+  # Value object representing a single attachment record on a +Comment+.
+  # Persisted in +CommentMetadata#attachments+; the gem owns the upload
+  # (see +PlanMyStuff::AttachmentUploader+) and stores the structured
+  # location (+owner+/+repo+/+sha+/+path+) of the uploaded file so the
+  # blob remains addressable across later branch rewrites.
+  #
+  # Mirrors +PlanMyStuff::Link+ / +PlanMyStuff::Approval+:
+  # +ActiveModel::Attributes+-backed, with +Serializers::JSON+ for
+  # round-trip through the metadata blob.
+  #
+  class Attachment
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Serializers::JSON
+
+    # @return [String] display filename (user-provided original name)
+    attribute :filename, :string
+    # @return [String] owner of the attachment repo (e.g. +"BrandsInsurance"+)
+    attribute :owner, :string
+    # @return [String] attachment repo name
+    attribute :repo, :string
+    # @return [String] commit SHA pinning the file
+    attribute :sha, :string
+    # @return [String] path within the attachment repo (no leading slash)
+    attribute :path, :string
+
+    validates :filename, :owner, :repo, :sha, :path, presence: true
+
+    # @return [String] blob-viewer URL for the pinned file
+    def url
+      "https://github.com/#{owner}/#{repo}/blob/#{sha}/#{path}"
+    end
+
+    # @return [Hash]
+    def to_h
+      { filename: filename, owner: owner, repo: repo, sha: sha, path: path }
+    end
+
+    # @param other [Object]
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      return false unless other.is_a?(PlanMyStuff::Attachment)
+
+      filename == other.filename && url == other.url
+    end
+
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [filename, url].hash
+    end
+
+    # Downloads the file via the GitHub Contents API (so it works on private repos) and writes the bytes to disk.
+    # Defaults the destination to +Dir.tmpdir+ joined with +File.basename(filename)+ (directory components
+    # stripped to prevent path traversal).
+    #
+    # @param dest [String, nil] destination path; defaults to +File.join(Dir.tmpdir, File.basename(filename))+
+    #
+    # @return [String] the path the bytes were written to
+    #
+    def download_to(dest = nil)
+      dest ||= File.join(Dir.tmpdir, File.basename(filename.to_s))
+      body = PlanMyStuff.client.rest(
+        :contents,
+        "#{owner}/#{repo}",
+        path: path,
+        ref: sha,
+        accept: 'application/vnd.github.raw',
+      )
+      File.binwrite(dest, body)
+      dest
+    end
+  end
+end

data/lib/plan_my_stuff/attachment_uploader.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'pathname'
+require 'securerandom'
+
+module PlanMyStuff
+  # Uploads attachment files to a shared attachment repo (+config.attachment_repo+ under +config.organization+) using
+  # GitHub's Git Data API, returning +PlanMyStuff::Attachment+ instances populated with the structured
+  # +owner+/+repo+/+sha+/+path+ location of each uploaded file.
+  #
+  # One commit per batch (atomic): all files in a single +upload_all!+ call land in the same tree/commit so partial
+  # failures cannot leave +config.main_branch+ in an inconsistent state.
+  #
+  # The attachment repo is assumed to exist; the uploader does not create it. Per-source-repo attachments are namespaced
+  # under +<repo_key>/issue-<number>/<uuid>.<ext>+, where +repo_key+ falls back to +repo.name+ for repos resolved
+  # without a +config.repos+ entry.
+  #
+  # @see PlanMyStuff::Attachment
+  #
+  class AttachmentUploader
+    class << self
+      # Uploads each entry in +files+ to the attachment repo and returns the resulting +Attachment+ instances. Order is
+      # not preserved: passthrough +Attachment+ entries are returned before newly-uploaded ones. +Attachment+ entries
+      # are passed through untouched (no upload), supporting round-trip through +Comment#save!+ without
+      # double-uploading.
+      #
+      # Empty / nil +files+ short-circuits with no API calls.
+      #
+      # @param repo [PlanMyStuff::Repo] source issues repo (used to namespace the path)
+      # @param issue_number [Integer]
+      # @param files [Array] mix of already-uploaded +PlanMyStuff::Attachment+ instances, uploaded-file objects
+      #   responding to +#path+ and +#original_filename+ (e.g. Rails +ActionDispatch::Http::UploadedFile+), and
+      #   String/Pathname paths to local files
+      #
+      # @return [Array<PlanMyStuff::Attachment>]
+      #
+      def upload_all!(repo:, issue_number:, files:)
+        entries = Array.wrap(files)
+        return [] if entries.empty?
+
+        slots = entries.map { |entry| classify(entry) }
+        attachments = slots.grep(PlanMyStuff::Attachment)
+        pending = slots.grep(Hash)
+
+        return attachments if pending.blank?
+
+        commit_sha = create_commit!(repo: repo, issue_number: issue_number, pending: pending)
+
+        pending.each do |slot|
+          slot[:attachment] = build_attachment(commit_sha: commit_sha, slot: slot)
+        end
+
+        publish_commit!(commit_sha)
+
+        attachments + pending.pluck(:attachment)
+      end
+
+      private
+
+        # Normalizes a single input entry into a slot Hash or itself (an existing Attachment);
+        # pending slots carry +{filename:, content:}+ awaiting upload.
+        #
+        # @param entry [Object]
+        #
+        # @return [PlanMyStuff::Attachment, Hash]
+        #
+        def classify(entry)
+          if entry.is_a?(PlanMyStuff::Attachment)
+            entry
+          else
+            filename, content = extract_filename_and_content(entry)
+            { filename: filename, content: content }
+          end
+        end
+
+        # @param entry [Object]
+        #
+        # @return [Array(String, String)] filename, raw bytes
+        #
+        def extract_filename_and_content(entry)
+          if entry.respond_to?(:path) && entry.respond_to?(:original_filename)
+            [leaf_filename(entry.original_filename), File.binread(entry.path)]
+          elsif entry.is_a?(String) || entry.is_a?(Pathname)
+            [File.basename(entry), File.binread(entry)]
+          else
+            raise(ArgumentError, "Unsupported attachment entry: #{entry.inspect}")
+          end
+        end
+
+        # Strips directory components (both POSIX and Windows separators) from a browser-supplied filename so
+        # values like +"../../secret.txt"+ or +"C:\\fakepath\\photo.jpg"+ cannot leak into stored metadata or
+        # later download paths.
+        #
+        # @param raw [Object] +original_filename+ from an uploaded-file-like object
+        #
+        # @return [String]
+        #
+        def leaf_filename(raw)
+          name = raw.to_s.tr('\\', '/').split('/').last
+          raise(ArgumentError, 'Attachment filename cannot be blank') if name.blank?
+
+          name
+        end
+
+        # Returns the path-segment used to namespace this source repo's attachments inside the shared attachment repo.
+        # Prefers +repo.key+ (registered repos); falls back to +repo.name+ for repos resolved by full name only.
+        #
+        # @param repo [PlanMyStuff::Repo]
+        #
+        # @return [String]
+        #
+        def namespace_for(repo)
+          (repo.key || repo.name).to_s
+        end
+
+        # Performs the Git Data API dance against the attachment repo and returns the new commit SHA without
+        # publishing it (the ref still points at the old head). Callers must invoke +publish_commit!+ after the
+        # batch has been converted into +Attachment+ instances so a failure during conversion leaves
+        # +config.main_branch+ untouched. Assumes the attachment repo and +config.main_branch+ exist.
+        #
+        # @param repo [PlanMyStuff::Repo] source issues repo
+        # @param issue_number [Integer]
+        # @param pending [Array<Hash>] slots awaiting upload
+        #
+        # @return [String] new commit SHA
+        #
+        def create_commit!(repo:, issue_number:, pending:)
+          client = PlanMyStuff.client
+          head_sha, base_tree_sha = fetch_head_and_tree(client)
+
+          assign_paths!(pending, namespace_for(repo), issue_number)
+          tree_items = pending.map { |slot| blob_tree_item(client, slot) }
+
+          new_tree = client.rest(:create_tree, attachment_repo_full_name, tree_items, base_tree: base_tree_sha)
+          new_tree_sha = dig_sha(new_tree, :sha)
+
+          new_commit = client.rest(
+            :create_commit,
+            attachment_repo_full_name,
+            "task: Add attachments for #{repo.full_name}##{issue_number}",
+            new_tree_sha,
+            [head_sha],
+          )
+          dig_sha(new_commit, :sha)
+        end
+
+        # Updates +config.main_branch+ to point at +commit_sha+. Called as the last step of +upload_all!+ so any
+        # earlier failure leaves the attachment repo unchanged.
+        #
+        # @param commit_sha [String]
+        #
+        # @return [void]
+        #
+        def publish_commit!(commit_sha)
+          PlanMyStuff.client.rest(:update_ref, attachment_repo_full_name, ref, commit_sha)
+        end
+
+        # @param client [PlanMyStuff::Client]
+        #
+        # @return [Array(String, String)] [head_sha, tree_sha]
+        #
+        def fetch_head_and_tree(client)
+          ref_response = client.rest(:ref, attachment_repo_full_name, ref)
+          head_sha = dig_sha(ref_response, :object, :sha)
+          commit_response = client.rest(:commit, attachment_repo_full_name, head_sha)
+          tree_sha = dig_sha(commit_response, :commit, :tree, :sha)
+          [head_sha, tree_sha]
+        end
+
+        # @param pending [Array<Hash>]
+        # @param namespace [String]
+        # @param issue_number [Integer]
+        #
+        # @return [void]
+        #
+        def assign_paths!(pending, namespace, issue_number)
+          pending.each do |slot|
+            uuid = SecureRandom.uuid
+            ext = File.extname(slot[:filename]).delete_prefix('.').downcase
+            basename = ext.empty? ? uuid : "#{uuid}.#{ext}"
+            slot[:basename] = basename
+            slot[:path] = "#{namespace}/issue-#{issue_number}/#{basename}"
+          end
+        end
+
+        # @param client [PlanMyStuff::Client]
+        # @param slot [Hash]
+        #
+        # @return [Hash] tree item ready for create_tree
+        #
+        def blob_tree_item(client, slot)
+          blob_sha = client.rest(
+            :create_blob, attachment_repo_full_name, Base64.strict_encode64(slot[:content]), 'base64',
+          )
+          { path: slot[:path], mode: '100644', type: 'blob', sha: blob_sha }
+        end
+
+        # @param commit_sha [String]
+        # @param slot [Hash]
+        #
+        # @return [PlanMyStuff::Attachment]
+        #
+        def build_attachment(commit_sha:, slot:)
+          PlanMyStuff::Attachment.new(
+            filename: slot[:filename],
+            owner: PlanMyStuff.configuration.organization,
+            repo: PlanMyStuff.configuration.attachment_repo,
+            sha: commit_sha,
+            path: slot[:path],
+          )
+        end
+
+        # @return [String] +"<organization>/<attachment_repo>"+
+        def attachment_repo_full_name
+          "#{PlanMyStuff.configuration.organization}/#{PlanMyStuff.configuration.attachment_repo}"
+        end
+
+        # @return [String] Git ref for the configured main branch (e.g. +"heads/main"+)
+        def ref
+          "heads/#{PlanMyStuff.configuration.main_branch}"
+        end
+
+        # Walks +keys+ through +obj+, tolerating Sawyer resources (method accessors), Hash with Symbol keys, and
+        # Hash with String keys.
+        #
+        # @param obj [Object]
+        # @param keys [Array<Symbol>]
+        #
+        # @return [Object, nil]
+        #
+        def dig_sha(obj, *keys)
+          keys.reduce(obj) do |acc, key|
+            break if acc.nil?
+
+            if acc.respond_to?(key)
+              acc.public_send(key)
+            elsif acc.respond_to?(:[])
+              acc[key] || acc[key.to_s]
+            end
+          end
+        end
+    end
+  end
+end