Add Fir generation support for heroku_app_release resource

[heroku-johnny]

Description

Work Item: W-19048405 [terraform-provider-heroku] Fir Compatibility: Release Task

This PR implements Fir generation support for the heroku_app_release resource, enabling artifact promotion workflows with OCI images for Fir apps while maintaining full backward compatibility with traditional Cedar slug workflows.

Key Features

• Artifact promotion: Deploy OCI images across Fir generation apps for build-once-deploy-everywhere workflows
• Generation validation: Automatic enforcement of Cedar=slug_id, Fir=oci_image artifact types
• OCI image support: Accept UUID and SHA256 digest formats matching Heroku's internal storage
• Plan & apply validation: Two-layer validation for comprehensive error handling with clear messaging

Changes

Schema Enhancement

• Add oci_image field (optional, conflicts with slug_id) for Fir generation apps
• Make slug_id optional (was required) with generation-aware validation
• Add mutual exclusivity validation ensuring exactly one artifact type
• Add OCI image format validation (UUID, SHA256 with prefix, bare SHA256)

App Release Resource Validation

• Add plan-time validation with dependency-aware logic in CustomizeDiff
• Add apply-time validation preventing incompatible artifact types
• Implement comprehensive error handling with actionable user guidance
• Update read function to extract OCI images from release artifacts
• Add unit tests covering all validation scenarios (6 test cases)

Usage Examples

# Cedar generation - traditional slugs (works as before)
resource "heroku_app_release" "cedar_release" {
  app_id      = heroku_app.cedar_app.id
  slug_id     = "01234567-89ab-cdef-0123-456789abcdef"
  description = "Deploy version 1.2.3"
}

# Fir generation - OCI image promotion
resource "heroku_app_release" "fir_release" {
  app_id      = heroku_app.fir_app.id  # App in Fir space
  oci_image   = "a4d4bfd7-3ff8-4a1d-963b-5b7367ba4e6f"  # From build or promotion
  description = "Deploy version 1.2.3 with CNB"
}

# Artifact promotion workflow
resource "heroku_build" "dev_build" {
  app_id = heroku_app.development.id
  source { path = "." }
}

resource "heroku_app_release" "staging" {
  app_id    = heroku_app.staging.id
  oci_image = var.oci_image_id  # Promote from dev
}

# This will FAIL with clear error:
resource "heroku_app_release" "invalid" {
  app_id    = heroku_app.fir_app.id
  slug_id   = "01234567-89ab-cdef-0123-456789abcdef"  # ❌ Error at plan time
}

Error Handling

Generation-aware validation prevents invalid configurations:

• Cedar apps: "Error: cedar generation apps must use slug_id, not oci_image"
• Fir apps: "Error: fir generation apps must use oci_image, not slug_id"
• Missing artifacts: "Error: either slug_id or oci_image must be provided"

Test Coverage

• Comprehensive unit tests for validation functions (2 test suites, 8 scenarios)
• Manual validation with real Heroku infrastructure:
  • Cedar app + slug_id (success)
  • Cedar app + oci_image (plan-time error)
  • Fir app + oci_image (success with artifact promotion)
  • Fir app + slug_id (plan-time error)
• End-to-end workflow confirmed OCI image extraction and state management

Documentation Updates

• Generation compatibility section with Cedar vs Fir artifact types
• OCI image formats documentation (UUID, SHA256 variants)
• Artifact promotion workflow examples for both generations
• Best practices section covering build-once-deploy-everywhere patterns
• Updated argument reference with generation-specific requirements table

Technical Implementation

• Enhanced read function: Extract OCI images from release artifacts array
• Two-layer validation: Plan-time (when possible) + apply-time (guaranteed)
• Dependency handling: Graceful plan-time behavior when app doesn't exist yet
• State management: Proper handling of generation-specific output attributes

---

Breaking Changes: None
Backward Compatible: Yes (slug_id workflows unchanged, only made optional)
Foundation: Extends existing generation validation patterns from previous fir compatibility PRs
Dependencies: Requires app generation detection from heroku_app fir compatibility PR

[mars]

This looks great 💯

The PR does appear to be targeting the incorrect base though, master instead of fir-compatibility.

[mars]

This still looks great, but now I caught a documentation issue.

[heroku-johnny]

This still looks great, but now I caught a documentation issue.

I did some more testing and same space does work as documented but cross-space doesn't yet. I updated the docs so that we can merge this and move on to pipelines and pipeline promotions