RUN-4083: Fix schedule day-of-month support and excessive API token creation (#215) (#217)

## Summary
This PR (v1.1.1) contains four important bug fixes:

1. **Schedule day-of-month support** - Fixes issue where job schedules
with day-of-month specifications were incorrectly converted, causing
"Provider produced inconsistent result after apply" errors.

2. **Excessive token creation** - Fixes issue where the provider created
a new "terraform-token" on every Terraform run, leading to hundreds of
unused tokens accumulating over time.

3. **Notification plugin parsing** - Fixes issue where single plugin
notifications were silently dropped because the API returns them as
objects instead of arrays.

4. **Combined notification targets** - Fixes issue where notification
blocks with multiple targets (email + plugin) were read back as separate
blocks.

## Changes

### Schedule Fix (Issue #215)
- Use Rundeck's `crontab` schedule format to preserve full cron
expressions
- Remove `normalizeCronSchedule()` that was incorrectly replacing
day-of-month with `?`
- Update `convertCronToScheduleObject()` to use crontab field instead of
structured format
- Enhance `convertScheduleObjectToCron()` to handle both crontab and
structured formats with dayofmonth support
- Improve wildcard logic to correctly distinguish between `*` (every
value) and `?` (no specific value)
- Handle edge case where both day-of-month and day-of-week are `?`

### Token Creation Fix
- The provider now reuses existing "terraform-token" entries instead of
creating a new token on every Terraform run
- Previously, each `terraform plan`, `apply`, or `refresh` would create
a new "terraform-token" in Rundeck
- The provider now checks for existing valid tokens before creating new
ones
- If multiple "terraform-token" entries exist (from previous versions),
the provider will reuse the first valid one found

### Notification Plugin Fix
- Fix `convertNotificationsFromJSON()` to handle both API response
formats:
- **Array format** (multiple plugins): `"plugin": [{"type": "...",
"configuration": {...}}]`
- **Single object format** (one plugin): `"plugin": {"type": "...",
"configuration": {...}}`
- Previously, single plugin notifications were silently dropped causing
"block count changed from N to N-1" errors

### Combined Notification Targets Fix
- Notification blocks with multiple targets (email + plugin, webhook +
email, etc.) now work correctly
- Previously, the provider would read these as separate notification
blocks, causing "block count changed from 1 to 2" errors
- Now a single notification block with multiple targets is preserved
correctly

## Testing

### Schedule Tests
- `TestAccJob_scheduleDayOfMonth`: Tests creating and updating jobs with
day-of-month schedules
- `TestAccJob_ScheduleDayOfMonthIntegration`: Validates schedule is
correctly stored in Rundeck API

### Notification Tests
Tested with configurations using combined notification targets:
```hcl
notification {
  type = "on_success"
  
  email {
    recipients = ["example@foo.bar"]
  }

  plugin {
    type = "PagerDutyEventNotification"
    config = {
      pagerdutyUrl     = "https://events.pagerduty.com"
      action           = "acknowledge"
      payload_severity = "info"
      images           = "https://www.rundeck.com/hubfs/rundeck-app-assets/rundeck-by-pagerduty-icon.png"
      payload_source   = "Rundeck"
      payload_summary  = "Rundeck Job Success Notification"
    }
  }
}
```

## Documentation
- Updated CHANGELOG.md for version 1.1.1
- Added scheduling examples in job resource documentation

## Example Use Cases

### Day-of-Month Schedule
```hcl
resource "rundeck_job" "monthly" {
  schedule = "0 0 09 10 * ? *"  # 9am on 10th of each month
}
```

### Combined Notification Targets
```hcl
resource "rundeck_job" "with_notifications" {
  notification {
    type = "on_success"
    
    email {
      recipients = ["team@example.com"]
    }
    
    plugin {
      type = "PagerDutyEventNotification"
      config = {
        action           = "resolve"
        payload_severity = "info"
      }
    }
  }
}
```

## Backwards Compatibility
✅ Fully backwards compatible with existing configurations:
- Existing schedules using weekday patterns continue to work
- Existing webhook and email notifications are unaffected
- Plugin notifications now work correctly
- Combined notification targets now work correctly
- Existing tokens are reused; no changes to authentication behavior

## Fixes
- Fixes #215 (schedule day-of-month support)
- Fixes excessive token creation issue
- Fixes notification plugin parsing issue
- Fixes combined notification targets issue

---------

Co-authored-by: Luis Toledo <luis@variacode.com>

Author: fdevans

.cursorrules

@@ -9,6 +9,7 @@ That file contains comprehensive guidelines for:
 - Code style requirements
 - Documentation standards
 - PR review checklist
+- Always use `make fmt` before commits to ensure CI/CD will pass.
 
 When working on this codebase, reference those instructions for detailed guidance.
 

CHANGELOG.md

@@ -1,3 +1,21 @@
+## 1.1.1
+
+**Bug Fixes**
+
+### Job Resource
+- **Fixed schedule day-of-month support** ([#215](https://github.com/rundeck/terraform-provider-rundeck/issues/215)) - Jobs can now be scheduled on specific days of the month using the day-of-month field in cron expressions (e.g., `schedule = "0 0 09 10 * ? *"` for 9am on the 10th of each month). Previously, the provider incorrectly replaced day-of-month values with `?`, causing "Provider produced inconsistent result" errors. The fix uses Rundeck's `crontab` schedule format to preserve the complete cron expression.
+
+- **Fixed notification plugin parsing** - Plugin notifications now work correctly when the Rundeck API returns a single plugin as an object instead of an array. Previously, single plugin notifications were silently dropped, causing "block count changed from N to N-1" errors. The fix handles both API response formats:
+  - Array format (multiple plugins): `"plugin": [{"type": "...", "configuration": {...}}]`
+  - Single object format (one plugin): `"plugin": {"type": "...", "configuration": {...}}`
+
+- **Fixed combined notification targets** - Notification blocks with multiple targets (e.g., email + plugin in the same block) now work correctly. Previously, the provider would read these as separate notification blocks, causing "block count changed from 1 to 2" errors. Now a single notification block with multiple targets is preserved correctly.
+
+### Provider Authentication
+- **Fixed excessive token creation** - The provider now reuses existing "terraform-token" entries instead of creating a new token on every Terraform run. Previously, each `terraform plan`, `apply`, or `refresh` would create a new "terraform-token" in Rundeck, leading to hundreds or thousands of unused tokens accumulating over time. The provider now checks for existing valid tokens before creating new ones. If multiple "terraform-token" entries exist (from previous versions), the provider will reuse the first valid one found. Users can manually clean up duplicate tokens via the Rundeck UI or API if desired.
+
+---
+
 ## 1.1.0
 
 **Important Changes**