plan_my_stuff 0.1.0 → 1.0.0

data/CONFIGURATION.md

@@ -0,0 +1,487 @@
+# Configuration
+
+Every PlanMyStuff option lives on `PlanMyStuff::Configuration`. The install generator drops a fully-commented copy at
+`config/initializers/plan_my_stuff.rb` — this file documents the same options grouped by concern. Defaults shown apply
+when the option is left unset.
+
+```ruby
+PMS.configure do |config|
+  # ...
+end
+```
+
+`PMS` is an alias for `PlanMyStuff`; consuming apps can use either.
+
+## Authentication (required)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `access_token` | `String` | — | GitHub PAT with `repo` and `project` scopes. Required. |
+| `import_access_token` | `String, nil` | `nil` | Classic PAT (requires `repo` scope) for the Issues Import API. Fine-grained tokens are not supported by that endpoint. |
+| `organization` | `String` | — | GitHub organization name. Required. |
+
+Both `access_token` and `organization` are validated by `config.validate!`; missing or blank values raise `PlanMyStuff::ConfigurationError`.
+
+> [!NOTE]
+> `import_access_token` is only required if you choose to use `PMS::Issue.import!`/`PMS::Issue.check_import!`
+
+```ruby
+config.access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_token)
+config.import_access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_import_token)
+config.organization = 'YourOrg'
+```
+
+## Repositories
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `repos` | `Hash{Symbol => String}` | `{}` | Named repo configs mapping a key to an `Org/Repo` string. |
+| `default_repo` | `Symbol, nil` | `nil` | Repo key used when callers omit the `repo:` param. |
+| `repo_nicknames` | `Hash{Symbol => String}` | `{}` | `Issue#to_param` prefix override (default `key.titleize`). |
+
+```ruby
+config.repos = { element: 'YourOrg/Element', underwriter: 'YourOrg/Underwriter' }
+config.default_repo = :element
+config.repo_nicknames = { safety: 'Compliance' } # :element -> "Element", :underwriter -> "Underwriter" come free
+```
+
+`repos` can be mutated via `config.repos[:key] = '...'` or set via `config.repos = { key: 'MyOrg/MyRepo' }`.
+`Issue#to_param` then returns `"Element-1234"` / `"Compliance-567"`, encoding both repo and number in a single
+URL segment so `youtrack_issue_path(@issue)` works without a `repo:` query param.
+
+## Attachments
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `attachment_repo` | `String` | `'pms-attachments'` | Bare repo (under `organization`) for uploaded attachments. |
+
+The repo must already exist; the uploader does not create it. Attachments commit onto
+`config.main_branch` under `<repo_key_or_name>/issue-<number>/<uuid>.<ext>`.
+
+```ruby
+config.attachment_repo = 'pms-attachments'
+```
+
+## Projects
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `default_project_number` | `Integer, nil` | `nil` | Default Projects V2 number for `add_to_project: true`. |
+| `testing_template_project_number` | `Integer, nil` | `nil` | Project to clone in `TestingProject.create!` instead of bootstrapping fields. |
+
+```ruby
+config.default_project_number = 14
+config.testing_template_project_number = 42
+```
+
+## App identity
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `app_name` | `String, nil` | `nil` | Stored in metadata so subscribers can attribute writes. |
+| `issues_url_prefix` | `String, nil` | `nil` | Prefix for `Issue#user_link`; the gem appends the issue number. |
+
+```ruby
+config.app_name = 'MyApp'
+
+url_options = Rails.application.routes.default_url_options
+config.issues_url_prefix = "#{url_options[:protocol] || 'http'}://#{url_options[:host]}/issues"
+```
+
+## User integration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `user_class` | `String` | `'User'` | Consuming app's user model class name, constantized for lookups. |
+| `display_name_method` | `Symbol` | `:to_s` | Method called on a user to get the display name for comment headers. |
+| `user_id_method` | `Symbol` | `:id` | Method called on a user to extract the app-side user ID. |
+| `support_method` | `Symbol, Proc` | `:support?` | Method name on the user, or a proc receiving the user, returning whether they're support staff. |
+| `github_login_for` | `Hash{Object => String}` | `{}` | Maps app user id (from `user_id_method`) to GitHub login. Powers the Take UI. |
+
+`support_method` may be a method name on the user object or a proc that receives the user and returns boolean.
+`github_login_for` maps app user id (whatever `user_id_method` returns) to GitHub login and powers the Take UI.
+
+```ruby
+config.user_class = 'User'
+config.display_name_method = :full_name
+config.user_id_method = :id
+config.support_method = :support?
+# or: config.support_method = -> (user) { user.role.in?(%w[support admin]) }
+config.github_login_for = {
+  1 => 'some_username',
+  2 => 'octocat',
+}
+```
+
+## Engine authentication
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `authenticate_with` | `Proc` | `nil` | Block executed as a `before_action` on every engine controller. |
+
+```ruby
+config.authenticate_with do
+  redirect_to main_app.login_path unless current_user
+end
+```
+
+## Markdown rendering
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `markdown_renderer` | `Symbol` | `:commonmarker` | Which markdown gem to use: `:commonmarker`, `:redcarpet`, or `nil` (raw HTML-escaped). |
+| `markdown_options` | `Hash` | `{}` | Default options passed to the renderer. Per-call options merge on top of these. |
+
+Set `markdown_renderer` to `:commonmarker`, `:redcarpet`, or `nil` (raw HTML-escaped). The chosen gem must be in your
+Gemfile.
+
+```ruby
+config.markdown_renderer = :commonmarker
+config.markdown_options = { render: { hardbreaks: true } }
+```
+
+## Notification actor
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `current_user` | `Proc, nil` | `nil` | Fallback actor for notification events when `user:` is not passed. |
+
+```ruby
+config.current_user = -> { Current.user }
+```
+
+## Controller rescue
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `controller_rescue` | `Proc, nil` | `nil` | Receives the rescued exception. Forward to your monitoring service. |
+
+```ruby
+config.controller_rescue = -> (error) { MonitoringService.notice_error(error) }
+```
+
+## Custom fields
+
+App-defined fields stored in metadata. Keys are field names; values are hashes with `:type` and `:required`.
+Supported types: `:string`, `:integer`, `:boolean`, `:array`, `:hash`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `custom_fields` | `Hash{Symbol => Hash}` | `{}` | Shared field definitions across all contexts. |
+| `issue_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Issue-only definitions; merged on top of shared. |
+| `comment_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Comment-only definitions; merged on top of shared. |
+| `project_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Project-only definitions; merged on top of shared. |
+| `testing_custom_fields` | `Hash{Symbol => Hash}` | `{}` | Testing-project-only definitions; merged on top of shared. |
+
+Context-specific config wins on key conflicts.
+
+```ruby
+config.custom_fields = {
+  notification_recipients: { type: :array, required: true },
+}
+config.issue_custom_fields = {
+  ticket_type: { type: :string, required: true },
+}
+config.comment_custom_fields = {
+  internal_note: { type: :boolean },
+}
+config.project_custom_fields = {
+  team: { type: :string },
+}
+config.testing_custom_fields = {
+  test_plan_url: { type: :string },
+}
+```
+
+## Issue types
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `issue_types` | `Hash{String => String}` | `{}` | Maps the gem's canonical issue type names to your org's display names. |
+
+Maps the gem's canonical type names (`'Bug'`, `'Feature'`, `'IT Issue / Hardware'`, `'Other'`, `'Performance'`,
+`'Question'`, `'Task'`) to whatever your org uses. Missing keys pass through unchanged.
+
+```ruby
+config.issue_types = {
+  'Bug' => 'User Bug',
+  'Feature' => 'Enhancement',
+}
+```
+
+## Issue Fields (public preview)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `issue_fields_enabled` | `Boolean` | `true` | Whether the Issue Fields public preview is wired up for the org. |
+| `issue_field_names` | `Hash{String => String}` | `{}` | Canonical Issue Field name => the consumer org's field name. |
+| `issue_field_values` | `Hash` | `{}` | Per field: canonical value => consumer value (single-select labels). |
+
+GitHub Issue Fields are structured per-issue metadata (text, number, date, or single-select)
+configured once at the org level. The preview is rolling out org-by-org. Leave this flag at its
+default (`true`) once your org has been admitted; flip to `false` to keep the gem from issuing
+calls that would otherwise return raw GraphQL errors.
+
+With the flag off:
+
+- `Issue#issue_fields` returns an empty `IssueFieldValueSet` without making a request.
+- `Issue#set_issue_fields!(...)` and `IssueField.list` raise `IssueFieldsNotEnabledError`.
+
+```ruby
+config.issue_fields_enabled = false   # org not admitted to the preview yet
+```
+
+`issue_field_names` and `issue_field_values` let a consuming org rename the native Issue Fields (and their
+single-select option labels) the gem refers to internally, the same way `pipeline_statuses` aliases pipeline
+statuses. Translation is bidirectional via `PlanMyStuff::IssueFieldTranslation`: canonical => consumer on writes and
+filters, consumer => canonical on reads, so internal comparisons (`awaiting_reply?`, `priority_list?`) keep working.
+Unmapped names / values pass through unchanged.
+
+```ruby
+config.issue_field_names = {
+  'Issue Status' => 'Status',
+  'Priority'     => 'Prio',
+}
+config.issue_field_values = {
+  'Issue Status' => {
+    'Submitted'        => 'Triaged',
+    'Waiting on Reply' => 'Awaiting Customer',
+    'Open'             => 'Open',
+    'Reopened'         => 'Reopened',
+  },
+}
+```
+
+## Release pipeline
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `pipeline_enabled` | `Boolean` | `true` | Whether the release pipeline feature is enabled. |
+| `pipeline_project_number` | `Integer, nil` | `nil` | Projects V2 number for the pipeline board. Falls back to `default_project_number`. |
+| `webhook_secret` | `String, nil` | `nil` | HMAC secret for GitHub webhook signature verification. Required when webhook routes are mounted. |
+| `pipeline_statuses` | `Hash{String => String}` | `{}` | Display aliases for canonical pipeline status names. |
+| `pipeline_testing_field_name` | `String` | `'Testing'` | Display name for the pipeline project's `Testing` single-select field. |
+| `pipeline_testing_values` | `Hash{Symbol => String}` | `{ active: 'Testing', inactive: 'Not testing' }` | Display labels for the canonical `:active`/`:inactive` testing options. |
+| `pipeline_completion_purge_enabled` | `Boolean` | `true` | Whether the sweep removes aged-out `Completed` items from the pipeline. |
+| `pipeline_completion_ttl_hours` | `Integer` | `24` | Hours after a `Completed` item's last update at which the sweep removes it. |
+| `main_branch` | `String` | `'main'` | Branch PRs merge into for the "Ready for Release" transition. |
+| `production_branch` | `String` | `'production'` | Branch PRs mereg into for the "Release in Progress" transition. |
+
+`pipeline_statuses` aliases the canonical status names (`'Submitted'`, `'Started'`, `'In Review'`, `'Testing'`,
+`'Ready for Release'`, `'Release in Progress'`, `'Completed'`) for display only. The constants remain the internal
+identifiers.
+
+`pipeline_completion_*` controls the sweep that removes aged-out `Completed` items from the pipeline. `webhook_secret`
+is required when webhook routes are mounted.
+
+```ruby
+config.pipeline_enabled = true
+config.pipeline_project_number = 14
+config.webhook_secret = Rails.application.credentials.dig(:plan_my_stuff, :webhook_secret)
+config.pipeline_statuses = {
+  'Submitted' => 'Triaged',
+  'Completed' => 'Done',
+}
+config.pipeline_testing_field_name = 'Testing'
+config.pipeline_testing_values = { active: 'Testing', inactive: 'Not testing' }
+config.pipeline_completion_purge_enabled = true
+config.pipeline_completion_ttl_hours = 24
+config.main_branch = 'main'
+config.production_branch = 'production'
+```
+
+## Follow-up reminders
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `reminders_enabled` | `Boolean` | `true` | Whether the reminders sweep performs any work. |
+| `reminder_days` | `Array<Integer>` | `[1, 3, 7, 10, 14, 18]` | Days-since-waiting at which reminder events fire. |
+| `inactivity_close_days` | `Integer` | `30` | Days of inactivity after which the sweep auto-closes a waiting issue. |
+| `waiting_on_user_label` | `String` | `'waiting-on-user'` | Label flagging issues waiting on an end-user reply. |
+| `waiting_on_approval_label` | `String` | `'waiting-on-approval'` | Label flagging issues waiting on pending approvals. |
+| `user_inactive_label` | `String` | `'user-inactive'` | Label applied to issues auto-closed by the inactivity sweep; removed when an issue is auto-reopened via a user reply. |
+
+Per-issue reminder override: `issue.metadata.reminder_days = [...]`.
+
+```ruby
+config.reminders_enabled = true
+config.reminder_days = [1, 3, 7, 10, 14, 18]
+config.inactivity_close_days = 30
+config.waiting_on_user_label = 'waiting-on-user'
+config.waiting_on_approval_label = 'waiting-on-approval'
+config.user_inactive_label = 'user-inactive'
+```
+
+## Auto-archiving
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `archiving_enabled` | `Boolean` | `true` | Whether the archive sweep performs any work. |
+| `archive_closed_after_days` | `Integer` | `90` | Days after `closed_at` at which a non-inactive-closed issue becomes an archive candidate. |
+| `archived_label` | `String` | `'archived'` | Label added to archived issues; also used by the sweep as a skip marker. |
+
+The archive sweep piggybacks `RemindersSweepJob`. Inactivity-closed and non-PMS issues are excluded.
+
+```ruby
+config.archiving_enabled = true
+config.archive_closed_after_days = 90
+config.archived_label = 'archived'
+```
+
+## AWS webhook
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `sns_topic_arn` | `String, nil` | `nil` | Expected SNS topic ARN for AWS webhook validation. |
+| `aws_service_identifier` | `String, nil` | `nil` | Suffix matched against ECS event resource ARNs (e.g. `'my-app-production-2-web-server'`). |
+| `production_commit_sha` | `String, nil` | `nil` | Prefix-matched against issue metadata `commit_sha` on `SERVICE_DEPLOYMENT_COMPLETED` events. |
+| `process_aws_webhooks` | `Boolean` | `Rails.env.production?` | Whether to process incoming AWS webhook events. |
+| `sns_verifier_class` | `Class` | `Aws::SNS::MessageVerifier` (when defined) | Class instantiated per request for SNS signature verification. Must respond to `authenticate!(raw_body)`. |
+| `sns_verifier_error` | `Class` | `Aws::SNS::MessageVerifier::VerificationError` (when defined) | Exception class rescued during SNS signature verification. |
+
+`production_commit_sha` is prefix-matched against issue metadata `commit_sha` on `SERVICE_DEPLOYMENT_COMPLETED` events.
+`sns_verifier_class` must respond to `authenticate!(raw_body)`.
+
+```ruby
+config.sns_topic_arn = 'arn:aws:sns:us-east-1:123456:ecs-deploy-topic'
+config.aws_service_identifier = 'myapp-production-web'
+config.production_commit_sha = Rails.configuration.x.image_tag
+config.process_aws_webhooks = Rails.env.production?
+config.sns_verifier_class = Aws::SNS::MessageVerifier
+config.sns_verifier_error = Aws::SNS::MessageVerifier::VerificationError
+```
+
+## Caching
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cache_enabled` | `Boolean` | `true` | ETag-based HTTP caching of GitHub reads via `Rails.cache`. |
+| `cache_version` | `String, nil` | `nil` | Opaque string baked into every PMS cache key; bump to invalidate. |
+
+```ruby
+config.cache_enabled = true
+config.cache_version = Rails.configuration.x.image_tag
+```
+
+## Route mounting
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `mount_groups` | `Hash{Symbol => Boolean}` | `{ webhooks: true, issues: true, projects: true }` | Per-group route mounting toggles. Set a key to `false` to skip mounting that group. |
+
+```ruby
+config.mount_groups = { webhooks: true, issues: true, projects: true }
+```
+
+## Boot behavior
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `eager_load_controllers_on_boot` | `Boolean` | `false` | Eager-load engine controllers in `after_initialize`. |
+
+Opt in if the host app probes engine controllers via `defined?` in dev mode. When `true`, the
+engine walks `app/controllers` once on boot so `defined?(PlanMyStuff::SomeController)` resolves
+without first referencing the constant.
+
+```ruby
+config.eager_load_controllers_on_boot = true
+```
+
+## Controller overrides
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `controllers` | `Hash{Symbol => String}` | `{}` | Per-route controller overrides. Keys are controllable route symbols; values are fully-qualified controller paths. |
+
+Per-route controller overrides. Keys are the controllable route symbols defined in
+`PlanMyStuff::Configuration::DEFAULT_CONTROLLERS`; values are fully-qualified controller paths. Unset keys fall back to
+the gem default.
+
+```ruby
+config.controllers[:issues] = 'my_app/issues'
+```
+
+Controllable keys (with gem defaults):
+
+| Key | Default |
+|---|---|
+| `: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/testings'` | `plan_my_stuff/issues/testings` |
+| `:'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` |
+
+### Customizing per-action behavior
+
+Every mounted route resolves its controller through `config.controller_for(key)`. Subclass a gem controller in your
+own app and register it to wedge in `before_action`s, authentication, or response tweaks - no monkey patching:
+
+```ruby
+# app/controllers/my_app/issues_controller.rb
+class MyApp::IssuesController < PMS::IssuesController
+  before_action :authenticate_user!
+  before_action :authorize_ticket_access
+end
+```
+
+```ruby
+# config/initializers/plan_my_stuff.rb
+PlanMyStuff.configure do |config|
+  config.controllers[:issues] = 'my_app/issues'
+end
+```
+
+For per-action side effects (audit log, metrics, notifications) without rewriting the action, yielding actions
+pass their primary object to an optional block on the happy path. Call `super do |obj| ... end` from a subclass:
+
+```ruby
+class MyApp::IssuesController < PMS::IssuesController
+  def create
+    super do |issue|
+      AuditLog.record(actor: current_user, action: :issue_created, target: issue)
+    end
+  end
+
+  def update
+    super do |issue|
+      AuditLog.record(actor: current_user, action: :issue_updated, target: issue)
+    end
+  end
+end
+```
+
+Contract:
+
+- The yield fires on the happy path, after the model load / write succeeds and before the gem's default
+  `flash[:success]` + `redirect_to`. Error branches, `not_found`, and authorization redirects do not yield.
+- Read actions (`index`, `show`, `new`, `edit`) yield before the implicit render; `index` yields the collection,
+  the rest yield the single object.
+- If your block calls `render` or `redirect_to`, the gem's default response is skipped (the action checks
+  `performed?`), so you can fully replace the response from the block.
+
+### Parent controller
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `parent_controller` | `String` | `'::ApplicationController'` | Parent of `PlanMyStuff::ApplicationController`. |
+
+Set this in `config/initializers/plan_my_stuff.rb`; Rails resolves the superclass once at class definition, so the
+value must be set before the engine's controllers load.
+
+```ruby
+config.parent_controller = 'RawrApplicationController'
+```