plan_my_stuff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03731d4c3b552639604aa37465eb9f2246eb6077ec40144b218b4afa2aefdc01
+  data.tar.gz: 0277ebbdc6a0f783c90cb1bcf2d73c6dfd79447ad52f1df8d547d217cf80e1bf
+SHA512:
+  metadata.gz: 3897dad435fd7b13780d3ac6ac3e25f9d15e49f58e8517c05ff6b28b78b7efd16216e4c9dbf0275afadf842821a9a006dd0e1c86b862e10927e197f190029f6a
+  data.tar.gz: 1a973153e39fc469580eac16dca37debb9780416b1cc7b50f9dffd440a6f64f4383fca30f24e72fdc02173c5875938c9181febd0226de8ecc8023c9907ac10db

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Brands Insurance Agency, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,284 @@
+# plan_my_stuff
+
+<!-- Badges (update once CI and RubyGems are configured) -->
+<!-- ![CI](https://github.com/BrandsInsurance/PlanMyStuff/actions/workflows/ci.yml/badge.svg) -->
+<!-- ![Gem Version](https://img.shields.io/gem/v/plan_my_stuff) -->
+<!-- ![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-red) -->
+
+A Rails engine gem that provides a GitHub-backed ticketing and project tracking layer for internal Rails apps. Wraps GitHub Issues and Projects V2 via Octokit, handling issue CRUD, comments with visibility controls, project board management, and a configurable request gateway.
+
+**Ruby:** >= 3.3 | **Rails:** >= 6.1, < 8 | **API client:** Octokit
+
+> [!IMPORTANT]
+> **commonmarker version compatibility:** This gem requires commonmarker v1.0+ (pinned `~> 2.7`). The v0.23 to v1.0 upgrade was a full rewrite with breaking changes:
+> - Module renamed: `CommonMarker` to `Commonmarker`
+> - Methods renamed: `render_html` to `to_html`, `render_doc` to `parse`
+> - Options changed from array of symbols (`[:HARDBREAKS]`) to nested hash (`options: { render: { hardbreaks: true } }`)
+> - Underlying engine changed from C (libcmark-gfm) to Rust (comrak)
+>
+> If your app already uses commonmarker < 1.0, you will need to upgrade. Alternatively, configure `markdown_renderer = :redcarpet` or `nil` to avoid the dependency entirely.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'plan_my_stuff'
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate plan_my_stuff:install
+```
+
+This creates `config/initializers/plan_my_stuff.rb` with documented configuration options.
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount PlanMyStuff::Engine, at: '/tickets'
+```
+
+### Markdown renderer
+
+The gem supports three markdown rendering options. The chosen gem must be in your Gemfile - `plan_my_stuff` does not declare either as a runtime dependency.
+
+| Option | Gemfile requirement | Config |
+|---|---|---|
+| commonmarker (default) | `gem 'commonmarker', '~> 2.7'` | `config.markdown_renderer = :commonmarker` |
+| redcarpet | `gem 'redcarpet'` | `config.markdown_renderer = :redcarpet` |
+| None (raw) | Nothing | `config.markdown_renderer = nil` |
+
+### Overriding views
+
+Copy the default views into your app for customization:
+
+```bash
+rails generate plan_my_stuff:views
+```
+
+## Configuration
+
+```ruby
+# config/initializers/plan_my_stuff.rb
+PlanMyStuff.configure do |config|
+  # Auth (PAT from a bot account with repo + project scopes)
+  config.access_token = ENV['PMS_GITHUB_TOKEN']
+
+  # Organization
+  config.organization = 'YourOrganization'
+
+  # Named repo configs
+  config.repos[:marketing_website] = 'YourOrganization/MarketingWebsite'
+  config.repos[:cms_website] = 'YourOrganization/CMSWebsite'
+  config.default_repo = :cms_website
+
+  # Default project board
+  config.default_project_number = 123
+
+  # User class (your app's model)
+  config.user_class = 'User'
+  config.display_name_method = :full_name
+  config.user_id_method = :id
+
+  # Support role check (symbol or proc)
+  config.support_method = :support?
+
+  # Markdown rendering (:commonmarker, :redcarpet, or nil)
+  config.markdown_renderer = :commonmarker
+
+  # Request gateway (proc or nil; nil = always send)
+  config.should_send_request = nil
+
+  # Background jobs (when gateway defers a request)
+  config.job_classes = {
+    create_ticket: 'PmsCreateTicketJob',
+    post_comment:  'PmsPostCommentJob',
+    update_status: 'PmsUpdateStatusJob'
+  }
+
+  # Deferred request notifications
+  config.deferred_notifier = nil
+  config.deferred_email_from = 'noreply@example.com'
+  config.deferred_email_to   = 'support@example.com'
+
+  # Custom fields (stored in issue/comment metadata)
+  config.custom_fields = {
+    ticket_type: { type: :string },
+    notification_recipients: { type: :array }
+  }
+
+  # App name (appears in metadata)
+  config.app_name = 'MyApp'
+end
+```
+
+The `PMS` alias is available for brevity: `PMS.configure`, `PMS::Issue.find`, etc.
+
+## Usage
+
+### Issues
+
+```ruby
+# Create
+issue = PMS::Issue.create!(
+  title: 'Login page broken on Safari',
+  body:  'Users report blank screen after clicking login...',
+  repo:  :cms_website,
+  labels: ['bug', 'app:cms_website'],
+  user:  current_user,
+  add_to_project: true
+)
+
+# Find
+issue = PMS::Issue.find(repo: :cms_website, number: 123)
+issue.title
+issue.body              # body without metadata
+issue.metadata          # PlanMyStuff::IssueMetadata
+issue.visible_to?(user) # visibility check
+issue.comments          # all comments
+issue.pms_comments      # only PMS-created comments
+
+# List
+issues = PMS::Issue.list(repo: :cms_website, state: :open, labels: ['bug'])
+
+# Update
+issue.update!(title: 'Updated title', labels: ['bug', 'P1'])
+
+# Close / Reopen
+issue.update!(state: :closed)
+issue.update!(state: :open)
+
+# Viewer management (visibility allowlist)
+PMS::Issue.add_viewers(repo: :cms_website, number: 123, user_ids: [5, 12])
+PMS::Issue.remove_viewers(repo: :cms_website, number: 123, user_ids: [5])
+```
+
+### Comments
+
+```ruby
+# Create
+comment = PMS::Comment.create!(
+  repo: :cms_website,
+  issue_number: 123,
+  body: 'Deployed fix to staging, please retest.',
+  user: current_user,
+  visibility: :public   # or :internal (support-only)
+)
+
+# List
+comments = PMS::Comment.list(repo: :cms_website, issue_number: 123)
+comments = PMS::Comment.list(repo: :cms_website, issue_number: 123, pms_only: true)
+
+comment.body            # visible text
+comment.metadata        # PlanMyStuff::CommentMetadata (nil for non-PMS comments)
+comment.visibility      # :public, :internal, or nil
+comment.pms_comment?    # true/false
+comment.visible_to?(user)
+```
+
+### Labels
+
+```ruby
+PMS::Label.add(repo: :cms_website, issue_number: 123, labels: ['in-progress'])
+PMS::Label.remove(repo: :cms_website, issue_number: 123, labels: ['triage'])
+```
+
+### Projects
+
+```ruby
+# List all projects
+projects = PMS::Project.list
+
+# View a project board
+project = PMS::Project.find(14)
+project.title
+project.statuses  # [{id: "ae429385", name: "On Deck"}, ...]
+project.items     # Array<PMS::ProjectItem>
+
+# Move item to a status column
+item = project.items.first
+item.move_to!('In Review')
+
+# Assign item
+item.assign!('octocat')
+
+# Add existing issue to project
+PMS::Project.add_item(project_number: 14, issue_repo: :cms_website, issue_number: 123)
+
+# Add draft item
+PMS::Project.add_draft_item(project_number: 14, title: 'Draft task', body: 'Details...')
+```
+
+## Metadata
+
+All state lives on GitHub. Issue and comment metadata is stored as a hidden HTML comment on the first line of the body:
+
+```html
+<!-- pms-metadata:{"gem_version":"0.0.0","app_name":"MyApp","created_at":"2026-03-24T10:00:00Z",...} -->
+```
+
+This is invisible when rendered on GitHub and parsed automatically by the gem into typed objects (`PMS::IssueMetadata`, `PMS::CommentMetadata`).
+
+## Verify setup
+
+```bash
+rails plan_my_stuff:verify
+```
+
+Checks token validity, org access, repo access, and project access.
+
+## Testing
+
+The gem provides test helpers for consuming apps:
+
+```ruby
+# spec/spec_helper.rb (or rails_helper.rb)
+require 'plan_my_stuff/test_helpers'
+
+RSpec.configure do |config|
+  config.include PlanMyStuff::TestHelpers
+end
+```
+
+Available in tests:
+
+```ruby
+PlanMyStuff.test_mode!  # stubs all API calls
+
+build_issue(title: 'Test issue')
+build_comment(body: 'Test comment')
+build_project(title: 'Test board')
+
+expect_pms_issue_created(title: 'Test issue')
+expect_pms_comment_created(body: 'Test comment')
+expect_pms_item_moved(status: 'In Review')
+```
+
+## Engine routes
+
+The engine provides these routes (all under the configured mount point):
+
+| Route | Action |
+|---|---|
+| `GET /` | Issue index |
+| `GET /issues/new` | New issue form |
+| `POST /issues` | Create issue |
+| `GET /issues/:id` | Issue detail with comments |
+| `GET /issues/:id/edit` | Edit issue form |
+| `PATCH /issues/:id` | Update issue |
+| `PATCH /issues/:id/close` | Close issue |
+| `PATCH /issues/:id/reopen` | Reopen issue |
+| `POST /issues/:id/comments` | Create comment |
+| `GET /issues/:id/comments/:id/edit` | Edit comment |
+| `PATCH /issues/:id/comments/:id` | Update comment |
+| `POST /issues/:id/labels` | Add label |
+| `DELETE /issues/:id/labels/:name` | Remove label |
+| `GET /projects` | Project list |
+| `GET /projects/:id` | Project board |
+| `POST /projects/:id/items` | Add item to project |
+| `PATCH /projects/:id/items/:id/move` | Move item |
+| `PATCH /projects/:id/items/:id/assign` | Assign item |
+

data/app/controllers/plan_my_stuff/application_controller.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class ApplicationController < ::ApplicationController
+    protect_from_forgery with: :exception
+    helper Rails.application.routes.url_helpers
+
+    before_action :authenticate_pms_user!
+
+    private
+
+      # Hook for consuming app authentication. Override this method in your
+      # ApplicationController, or configure via PlanMyStuff.configure:
+      #
+      #   PlanMyStuff.configure do |config|
+      #     config.authenticate_with do
+      #       redirect_to login_path unless current_user
+      #     end
+      #   end
+      #
+      def authenticate_pms_user!
+        pms_auth = PlanMyStuff.configuration.authenticate_with
+        instance_exec(&pms_auth) if pms_auth
+      end
+
+      # Returns the current user for PMS visibility checks.
+      # Delegates to the consuming app's current_user method.
+      #
+      # @return [Object, nil]
+      #
+      def pms_current_user
+        return current_user if respond_to?(:current_user, true)
+      end
+
+      # @return [Boolean]
+      def support_user?
+        pms_current_user.present? && PMS::UserResolver.support?(pms_current_user)
+      end
+
+      # Redirects non-support users back with an error.
+      #
+      # @param path [String] redirect destination
+      # @param message [String]
+      #
+      # @return [void]
+      #
+      def redirect_to_unauthorized(path, message: 'You do not have permission to perform this action.')
+        flash[:error] = message
+        redirect_to(path)
+      end
+
+      # Splits a comma-separated labels string into an array.
+      #
+      # @param labels_string [String, nil]
+      #
+      # @return [Array<String>]
+      #
+      def parse_labels(labels_string)
+        return [] if labels_string.blank?
+
+        labels_string.split(',').filter_map { |l| l.strip.presence }
+      end
+
+      # Parses a comma-separated string of viewer IDs into an array of integers.
+      #
+      # @param ids_string [String, nil]
+      #
+      # @return [Array<Integer>]
+      #
+      def parse_viewer_ids(ids_string)
+        return [] if ids_string.blank?
+
+        ids_string.split(',').filter_map { |id| id.strip.presence&.to_i }
+      end
+  end
+end

data/app/controllers/plan_my_stuff/comments_controller.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class CommentsController < ApplicationController
+    # POST /issues/:issue_id/comments
+    def create
+      @issue = PMS::Issue.find(params[:issue_id].to_i, repo: params[:repo]&.to_sym)
+
+      PMS::Comment.create!(
+        issue: @issue,
+        body: comment_params[:body],
+        user: pms_current_user,
+        visibility: comment_params[:visibility]&.to_sym || :public,
+      )
+
+      flash[:success] = 'Comment was successfully created.'
+      redirect_to(plan_my_stuff.issue_path(@issue.number))
+    end
+
+    # GET /issues/:issue_id/comments/:id/edit
+    def edit
+      load_comment
+      return unless @comment
+
+      @support_user = support_user?
+      return redirect_to_unauthorized(plan_my_stuff.issue_path(@issue.number)) unless can_edit?(@comment)
+    end
+
+    # PATCH/PUT /issues/:issue_id/comments/:id
+    def update
+      load_comment
+      return unless @comment
+
+      @support_user = support_user?
+      return redirect_to_unauthorized(plan_my_stuff.issue_path(@issue.number)) unless can_edit?(@comment)
+
+      update_attrs = { body: comment_params[:body] }
+      update_attrs[:visibility] = comment_params[:visibility].to_sym if @support_user && comment_params[:visibility]
+
+      @comment.update!(**update_attrs)
+
+      flash[:success] = 'Comment was successfully updated.'
+      redirect_to(plan_my_stuff.issue_path(@issue.number))
+    rescue PMS::StaleObjectError
+      flash.now[:error] = 'Comment 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 comment_params
+        params.require(:comment).permit(:body, :visibility)
+      end
+
+      # Loads the issue and comment from params.
+      #
+      # @return [void]
+      #
+      def load_comment
+        @issue = PMS::Issue.find(params[:issue_id].to_i, repo: params[:repo]&.to_sym)
+        @comment = PMS::Comment.find(params[:id].to_i, issue: @issue)
+      end
+
+      # Returns true if the current user can edit the given comment.
+      # Support users can edit any comment. Regular users can only edit
+      # their own comments.
+      #
+      # @param comment [PlanMyStuff::Comment]
+      #
+      # @return [Boolean]
+      #
+      def can_edit?(comment)
+        return true if support_user?
+
+        user = pms_current_user
+        return false if user.blank?
+
+        comment.metadata.created_by == PMS::UserResolver.user_id(user)
+      end
+  end
+end

data/app/controllers/plan_my_stuff/issues_controller.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class IssuesController < ApplicationController
+    # GET /issues
+    def index
+      @page = (params[:page] || 1).to_i
+      @per_page = (params[:per_page] || 25).to_i
+      @state = (params[:state] || 'open').to_sym
+      @labels = params[:labels].present? ? Array.wrap(params[:labels]) : []
+      @repo = params[:repo]&.to_sym
+
+      @issues = PMS::Issue.list(
+        repo: @repo,
+        state: @state,
+        labels: @labels,
+        page: @page,
+        per_page: @per_page,
+      )
+    end
+
+    # GET /issues/new
+    def new
+      @issue = PMS::Issue.new
+      @support_user = support_user?
+    end
+
+    # POST /issues
+    def create
+      @issue = PMS::Issue.create!(
+        title: issue_params[:title],
+        body: issue_params[:body],
+        labels: parse_labels(issue_params[:labels]),
+        user: pms_current_user,
+      )
+
+      flash[:success] = 'Issue was successfully created.'
+      redirect_to(plan_my_stuff.issue_path(@issue.number))
+    rescue PMS::ValidationError => e
+      @issue = PMS::Issue.new(title: issue_params[:title], body: issue_params[:body])
+      @support_user = support_user?
+      flash.now[:error] = e.message
+      render(:new, status: PMS.unprocessable_status)
+    end
+
+    # GET /issues/:id
+    def show
+      @issue = PMS::Issue.find(params[:id].to_i, repo: params[:repo]&.to_sym)
+      @comments = filter_visible_comments(@issue.comments)
+      @support_user = support_user?
+      @current_user_id = pms_current_user.present? ? PMS::UserResolver.user_id(pms_current_user) : nil
+    end
+
+    # GET /issues/:id/edit
+    def edit
+      @issue = PMS::Issue.find(params[:id].to_i, repo: params[:repo]&.to_sym)
+      @support_user = support_user?
+    end
+
+    # PATCH/PUT /issues/:id
+    def update
+      @issue = PMS::Issue.find(params[:id].to_i, repo: params[:repo]&.to_sym)
+
+      @issue.update!(
+        title: issue_params[:title],
+        body: issue_params[:body],
+        labels: parse_labels(issue_params[:labels]),
+      )
+
+      flash[:success] = 'Issue was successfully updated.'
+      redirect_to(plan_my_stuff.issue_path(@issue.number))
+    rescue PMS::StaleObjectError
+      @support_user = support_user?
+      flash.now[:error] = 'Issue was modified by someone else. Please review the latest changes and try again.'
+      render(:edit, status: PMS.unprocessable_status)
+    end
+
+    # PATCH /issues/:id/close
+    def close
+      @issue = PMS::Issue.find(params[:id].to_i, repo: params[:repo]&.to_sym)
+      @issue.update!(state: :closed)
+
+      flash[:success] = 'Issue was successfully closed.'
+      redirect_to(plan_my_stuff.issue_path(@issue.number))
+    end
+
+    # PATCH /issues/:id/reopen
+    def reopen
+      @issue = PMS::Issue.find(params[:id].to_i, repo: params[:repo]&.to_sym)
+      @issue.update!(state: :open)
+
+      flash[:success] = 'Issue was successfully reopened.'
+      redirect_to(plan_my_stuff.issue_path(@issue.number))
+    end
+
+    # POST /issues/:id/add_viewers
+    def add_viewers
+      return redirect_to_unauthorized(plan_my_stuff.issue_path(params[:id])) unless support_user?
+
+      viewer_ids = parse_viewer_ids(params[:viewer_ids])
+      if viewer_ids.blank?
+        flash[:error] = 'No valid viewer IDs provided.'
+        redirect_to(plan_my_stuff.edit_issue_path(params[:id]))
+        return
+      end
+
+      PMS::Issue.add_viewers(number: params[:id].to_i, user_ids: viewer_ids, repo: params[:repo]&.to_sym)
+
+      flash[:success] = 'Viewers were successfully added.'
+      redirect_to(plan_my_stuff.edit_issue_path(params[:id]))
+    end
+
+    # DELETE /issues/:id/remove_viewer
+    def remove_viewer
+      return redirect_to_unauthorized(plan_my_stuff.issue_path(params[:id])) unless support_user?
+
+      viewer_id = params[:viewer_id].to_i
+      PMS::Issue.remove_viewers(number: params[:id].to_i, user_ids: [viewer_id], repo: params[:repo]&.to_sym)
+
+      flash[:success] = 'Viewer was successfully removed.'
+      redirect_to(plan_my_stuff.edit_issue_path(params[:id]))
+    end
+
+    private
+
+      # @return [ActionController::Parameters]
+      def issue_params
+        params.require(:issue).permit(:title, :body, :labels)
+      end
+
+      # Filters comments to only those visible to the current user.
+      # Falls back to showing all comments if no current_user is available.
+      #
+      # @param comments [Array<PlanMyStuff::Comment>]
+      #
+      # @return [Array<PlanMyStuff::Comment>]
+      #
+      def filter_visible_comments(comments)
+        user = pms_current_user
+        return comments unless user
+
+        comments.select { |comment| comment.visible_to?(user) }
+      end
+  end
+end

data/app/controllers/plan_my_stuff/labels_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class LabelsController < ApplicationController
+    # POST /issues/:issue_id/labels
+    def add_to_issue
+      labels = parse_labels(params[:label_name])
+      if labels.blank?
+        flash[:error] = 'Label name is required.'
+        redirect_to(plan_my_stuff.issue_path(params[:issue_id]))
+        return
+      end
+
+      issue = PMS::Issue.find(params[:issue_id].to_i, repo: params[:repo]&.to_sym)
+      PMS::Label.add(issue: issue, labels: labels)
+
+      flash[:success] = 'Label was successfully added.'
+      redirect_to(plan_my_stuff.issue_path(issue.number))
+    end
+
+    # DELETE /issues/:issue_id/labels/:name
+    def remove_from_issue
+      issue = PMS::Issue.find(params[:issue_id].to_i, repo: params[:repo]&.to_sym)
+      PMS::Label.remove(issue: issue, labels: [params[:name]])
+
+      flash[:success] = 'Label was successfully removed.'
+      redirect_to(plan_my_stuff.issue_path(issue.number))
+    end
+  end
+end