cpflow 5.1.1 → 5.3.0

data/lib/core/doctor_service.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class DoctorService
+class DoctorService # rubocop:disable Metrics/ClassLength
   class ValidationError < StandardError; end
 
   extend Forwardable
@@ -36,12 +36,12 @@ class DoctorService
 
   def validate_config
     check_for_app_names_contained_in_others
+    check_deploy_orders
   end
 
   def validate_templates
     @template_parser = TemplateParser.new(@command)
-    filenames = Dir.glob("#{@template_parser.template_dir}/*.yml")
-    templates = @template_parser.parse(filenames)
+    templates = @template_parser.parse(template_filenames)
 
     check_for_duplicate_templates(templates)
     warn_deprecated_template_variables
@@ -60,6 +60,12 @@ class DoctorService
     raise ValidationError, "#{Shell.color("ERROR: #{message}", :red)}\n#{list}"
   end
 
+  def check_deploy_orders
+    config.validate_deploy_orders!
+  rescue RuntimeError => e
+    raise ValidationError, Shell.color("ERROR: #{e.message}", :red)
+  end
+
   def find_app_names_contained_in_others # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
     app_names = config.apps.keys.map(&:to_s).sort
     app_prefixes = config.apps
@@ -88,6 +94,41 @@ class DoctorService
     raise ValidationError, "#{Shell.color("ERROR: #{message}", :red)}\n#{list}"
   end
 
+  def template_filenames
+    return existing_arg_template_filenames if config.args.any?
+
+    message = "ERROR: Can't find current config, please specify an app."
+    raise ValidationError, Shell.color(message, :red) if config.current.nil?
+
+    template_names = config.current[:setup_app_templates]
+    # Fall back to every template in the directory when setup_app_templates is unconfigured.
+    return Dir.glob("#{@template_parser.template_dir}/*.yml") if template_names.nil? || template_names.empty?
+
+    # When setup_app_templates is configured, validate only that selected subset,
+    # including the deprecation scan.
+    resolve_template_filenames(template_names)
+  end
+
+  def existing_arg_template_filenames = resolve_template_filenames(config.args)
+
+  def resolve_template_filenames(template_names)
+    unique_template_names = template_names.uniq
+    filenames = unique_template_names.map { |name| @template_parser.template_filename(name) }
+    ensure_templates_exist!(unique_template_names, filenames)
+    filenames
+  end
+
+  def ensure_templates_exist!(template_names, filenames)
+    missing_templates = template_names.zip(filenames).reject { |_, filename| File.exist?(filename) }
+    return if missing_templates.empty?
+
+    missing_templates_str = missing_templates.map do |name, filename|
+      "  - #{name} (#{filename})"
+    end.join("\n")
+    message = "#{Shell.color('Missing templates:', :red)}\n#{missing_templates_str}"
+    raise ValidationError, message
+  end
+
   def warn_deprecated_template_variables
     deprecated_variables = @template_parser.deprecated_variables
     return if deprecated_variables.empty?

data/lib/core/shell.rb

@@ -65,15 +65,22 @@ class Shell
     tmp_stderr && !verbose
   end
 
-  def self.cmd(*cmd_to_run, capture_stderr: false)
-    output, status = capture_stderr ? Open3.capture2e(*cmd_to_run) : Open3.capture2(*cmd_to_run)
+  def self.cmd(*cmd_to_run, capture_stderr: false, separate_stderr: false)
+    return cmd_with_separate_stderr(*cmd_to_run) if separate_stderr
 
+    output, status = capture_stderr ? Open3.capture2e(*cmd_to_run) : Open3.capture2(*cmd_to_run)
     {
       output: output,
       success: status.success?
     }
   end
 
+  def self.cmd_with_separate_stderr(*cmd_to_run)
+    output, error_output, status = Open3.capture3(*cmd_to_run)
+    { output: output, error_output: error_output, success: status.success? }
+  end
+  private_class_method :cmd_with_separate_stderr
+
   #
   # Hide sensitive data based on the passed pattern
   #

data/lib/core/template_parser.rb

@@ -37,38 +37,72 @@ class TemplateParser
   private
 
   def replace_variables(yaml_file) # rubocop:disable Metrics/MethodLength
+    original_yaml_file = yaml_file
+    yaml_file = replace_legacy_variables(yaml_file)
+
     yaml_file = yaml_file
                 .gsub("{{APP_ORG}}", config.org)
                 .gsub("{{APP_NAME}}", config.app)
                 .gsub("{{APP_LOCATION}}", config.location)
                 .gsub("{{APP_LOCATION_LINK}}", config.location_link)
-                .gsub("{{APP_IMAGE}}", cp.latest_image)
-                .gsub("{{APP_IMAGE_LINK}}", config.image_link(cp.latest_image))
                 .gsub("{{APP_IDENTITY}}", config.identity)
                 .gsub("{{APP_IDENTITY_LINK}}", config.identity_link)
                 .gsub("{{APP_SECRETS}}", config.secrets)
                 .gsub("{{APP_SECRETS_POLICY}}", config.secrets_policy)
+    yaml_file = replace_image_variables(yaml_file)
 
     config.shared_secret_placeholders.each do |placeholder, secret_name|
       yaml_file = yaml_file.gsub(placeholder, secret_name)
     end
 
-    find_deprecated_variables(yaml_file)
+    find_deprecated_variables(original_yaml_file)
+    yaml_file
+  end
+
+  def replace_image_variables(yaml_file)
+    has_image = yaml_file.include?("{{APP_IMAGE}}")
+    has_image_link = yaml_file.include?("{{APP_IMAGE_LINK}}")
+    return yaml_file unless has_image || has_image_link
 
-    # Kept for backwards compatibility
+    yaml_file = yaml_file.gsub("{{APP_IMAGE}}", latest_image) if has_image
+    yaml_file = yaml_file.gsub("{{APP_IMAGE_LINK}}", config.image_link(latest_image)) if has_image_link
     yaml_file
-      .gsub("APP_ORG", config.org)
-      .gsub("APP_GVC", config.app)
-      .gsub("APP_LOCATION", config.location)
-      .gsub("APP_IMAGE", cp.latest_image)
+  end
+
+  # Kept for backwards compatibility.
+  def replace_legacy_variables(yaml_file)
+    yaml_file
+      .gsub(deprecated_variable_pattern("APP_ORG"), config.org)
+      .gsub(deprecated_variable_pattern("APP_GVC"), config.app)
+      .gsub(deprecated_variable_pattern("APP_LOCATION"), config.location)
+      .then { |updated_yaml| replace_legacy_image_variable(updated_yaml) }
+  end
+
+  def replace_legacy_image_variable(yaml_file)
+    return yaml_file unless deprecated_variable_used?(yaml_file, "APP_IMAGE")
+
+    yaml_file.gsub(deprecated_variable_pattern("APP_IMAGE"), latest_image)
+  end
+
+  def latest_image
+    # Share one image value across modern and legacy image replacements in this parser instance.
+    @latest_image ||= cp.latest_image
   end
 
   def find_deprecated_variables(yaml_file)
     new_variables.each do |old_key, new_key|
-      @deprecated_variables[old_key] = new_key if yaml_file.include?(old_key)
+      @deprecated_variables[old_key] = new_key if deprecated_variable_used?(yaml_file, old_key)
     end
   end
 
+  def deprecated_variable_used?(yaml_file, old_key)
+    yaml_file.match?(deprecated_variable_pattern(old_key))
+  end
+
+  def deprecated_variable_pattern(old_key)
+    /(?<!\{\{)\b#{Regexp.escape(old_key)}\b(?!\}\})/
+  end
+
   def new_variables
     {
       "APP_ORG" => "{{APP_ORG}}",

data/lib/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "5.1.1"
+  VERSION = "5.3.0"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/generator_templates/controlplane.yml

@@ -48,10 +48,9 @@ apps:
     #   - name: database
     #     secret_name: __APP_PREFIX__-review-database-secrets
     #     policy_name: __APP_PREFIX__-review-database-secrets-policy
-    # Uncomment to automatically initialize and tear down review-app databases:
+    # Uncomment to automatically initialize review-app databases:
     # hooks:
     #   post_creation: bundle exec rails db:prepare
-    #   pre_deletion: bundle exec rails db:drop
 
   __APP_PREFIX__-production:
     <<: *production

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -1,10 +1,9 @@
-# Review App Commands
+# Review App Help
 
+You asked for review app help.
 These commands are generated by [cpflow](https://github.com/shakacode/control-plane-flow).
-For full setup, version-pinning, and troubleshooting details, see the upstream
-[CI automation guide](https://github.com/shakacode/control-plane-flow/blob/__CPFLOW_GITHUB_ACTIONS_REF__/docs/ci-automation.md).
 
-## Pull Request Commands
+## Review App Commands
 
 Comment with exactly one command, with no surrounding text or trailing spaces.
 A single trailing newline from GitHub's comment editor is accepted.
@@ -15,13 +14,19 @@ A single trailing newline from GitHub's comment editor is accepted.
 | `+review-app-delete` | Deletes the review app. This also runs automatically when the PR closes. |
 | `+review-app-help` | Posts this help message on the PR. |
 
-## Standard Setup
+For complete setup, version-pinning, and troubleshooting guidance, see the upstream
+[CI automation guide](https://github.com/shakacode/control-plane-flow/blob/__CPFLOW_GITHUB_ACTIONS_REF__/docs/ci-automation.md).
+
+<details>
+<summary>GitHub Actions setup options</summary>
 
-For the normal generated review-app path, GitHub needs one repository secret:
+## GitHub Actions Secrets
+
+For the normal generated review-app path, GitHub Actions needs one secret:
 
 | Name | Where | Notes |
 | --- | --- | --- |
-| `CPLN_TOKEN_STAGING` | Repository secret | Control Plane service-account token for the staging/review org. |
+| `CPLN_TOKEN_STAGING` | GitHub Actions secret | Service-account token scoped to the staging Control Plane org on controlplane.com. |
 
 For public repositories, use a staging/review token that cannot access
 production Control Plane resources. Generated review-app deploys skip fork PR
@@ -29,7 +34,9 @@ heads because Docker builds use repository secrets. If a forked change needs a
 review app, first move the reviewed change to a trusted branch in this
 repository.
 
-No repository variables are required for the standard review-app path when
+## GitHub Actions Variables
+
+No GitHub Actions variables are required for the standard review-app path when
 `.controlplane/controlplane.yml` has exactly one review app entry with
 `match_if_app_name_starts_with: true`. cpflow infers the review-app prefix and
 staging org from that config.
@@ -40,14 +47,26 @@ review-app secret dictionaries limited to disposable databases, review-only
 renderer credentials, and license values that are acceptable for review-app
 exposure.
 
+For public demos, starter staging apps, and long-lived review apps, keep the app
+workload `type: standard` with one warm replica, set its autoscaling metric to
+`disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and
+memory allocation at that fixed replica count. Shared Postgres and other
+stateful workloads are the usual exceptions and should stay manually sized;
+Capacity AI is for supported stateless app/service workloads. If true idle
+scale-to-zero is explicitly required, create a separate `serverless` workload
+before the first deploy or plan a delete/recreate migration because Control
+Plane will not change an existing `standard` workload to `serverless` in place.
+
 Optional overrides exist for forks, clones, and unusual apps:
 
 | Name | Notes |
 | --- | --- |
-| `CPLN_ORG_STAGING` | Override the staging/review Control Plane org inferred from `controlplane.yml`. |
+| `CPLN_ORG_STAGING` | Control Plane org on controlplane.com for staging and review apps. Overrides the org inferred from `controlplane.yml`. |
 | `REVIEW_APP_PREFIX` | Override the review-app prefix inferred from `controlplane.yml`. |
 | `PRIMARY_WORKLOAD` | Public workload used for review URLs and health checks; defaults to `rails`. |
 
+</details>
+
 ## Staging And Production
 
 Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
@@ -108,6 +127,9 @@ gh secret list --org OWNER | grep '^CPLN_TOKEN_PRODUCTION[[:space:]]' || true
 Before the first promotion, bootstrap the production app the same way in the
 production org, using production-only secrets and values.
 
+<details>
+<summary>Version locking and advanced options</summary>
+
 ## Version Locking
 
 Generated wrappers pin Control Plane Flow with a release tag, for example
@@ -147,7 +169,7 @@ bin/pin-cpflow-github-ref <40-character-control-plane-flow-commit-sha>
 bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow
 ```
 
-## Advanced Variables
+## Advanced GitHub Actions Variables
 
 Most apps do not need these:
 
@@ -166,3 +188,5 @@ that copy the workflow before configuring Control Plane can remove
 `.github/workflows/cpflow-review-app-help.yml` or uncomment and adapt the
 wrapper-level `if:` guard shown in that file, for example
 `vars.REVIEW_APP_PREFIX != '' || vars.CPLN_ORG_STAGING != ''`.
+
+</details>

data/lib/github_flow_templates/.github/workflows/cpflow-delete-review-app.yml

@@ -1,5 +1,7 @@
 name: Delete Review App
 
+run-name: "Delete Review App - PR #${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}"
+
 on:
   pull_request_target:
     types: [closed]
@@ -11,9 +13,15 @@ on:
         description: Pull request number targeted for deletion
         required: true
         type: number
+      reconcile_intent_run_id:
+        description: Authenticated internal handoff; manual values are rejected
+        required: false
+        type: string
 
 permissions:
+  actions: write
   contents: read
+  deployments: write
   issues: write
   pull-requests: write
 
@@ -22,6 +30,8 @@ jobs:
     # pull_request_target is intentional: fork PR-close events need access to
     # staging secrets to delete review apps and update PR comments. The upstream
     # reusable workflow checks out trusted base-branch action code, not fork code.
+    # author_association is a cheap caller-side cost filter. The reusable workflow
+    # still checks the commenter's current repository permission before privileged work.
     if: |
       (github.event_name == 'issue_comment' &&
        github.event.issue.pull_request &&

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml

@@ -13,15 +13,24 @@ on:
         description: Pull request number to deploy
         required: true
         type: number
+      reconcile_intent_run_id:
+        description: Authenticated internal handoff; manual values are rejected
+        required: false
+        type: string
 
 permissions:
+  actions: write
   contents: read
   deployments: write
   issues: write
   pull-requests: write
 
 jobs:
+  # The reusable job exposes `image_built`; downstream jobs can read
+  # `needs.deploy.outputs.image_built`. A value of `false` means this check did not validate the Docker image.
   deploy:
+    # author_association is a cheap caller-side cost filter. The reusable workflow
+    # still checks the commenter's current repository permission before privileged work.
     if: |
       (github.event_name == 'pull_request' &&
        github.event.pull_request.head.repo.full_name == github.repository) ||

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpflow
 version: !ruby/object:Gem::Version
-  version: 5.1.1
+  version: 5.3.0
 platform: ruby
 authors:
 - Justin Gordon
@@ -75,7 +75,16 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".agents/agent-workflow.yml"
+- ".agents/bin/README.md"
+- ".agents/bin/docs"
+- ".agents/bin/lint"
+- ".agents/bin/setup"
+- ".agents/bin/test"
+- ".agents/bin/validate"
+- ".agents/trusted-github-actors.yml"
 - ".agents/workflows/address-review.md"
+- ".agents/workflows/ai-rollout-e2e-test.md"
 - ".claude/commands/address-review.md"
 - ".claude/commands/update-changelog.md"
 - ".github/actions/cpflow-build-docker-image/action.yml"
@@ -86,6 +95,7 @@ files:
 - ".github/actions/cpflow-setup-environment/action.yml"
 - ".github/actions/cpflow-validate-config/action.yml"
 - ".github/actions/cpflow-wait-for-health/action.yml"
+- ".github/pull_request_template.md"
 - ".github/workflows/check_cpln_links.yml"
 - ".github/workflows/claude-code-review.yml"
 - ".github/workflows/claude.yml"
@@ -106,7 +116,9 @@ files:
 - ".overcommit.yml"
 - ".rubocop.yml"
 - ".simplecov_spawn.rb"
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - COMM-LICENSE.txt
 - CONTRIBUTING.md
 - Gemfile
@@ -137,12 +149,20 @@ files:
 - docs/ci-automation.md
 - docs/commands.md
 - docs/dns.md
+- docs/grafana-opentelemetry.md
 - docs/migrating-heroku-to-control-plane.md
 - docs/postgres.md
 - docs/rds-private-networking.md
 - docs/redis.md
 - docs/releasing.md
 - docs/secrets-and-env-values.md
+- docs/sidebars.ts
+- docs/telemetry/application-instrumentation.md
+- docs/telemetry/collector.md
+- docs/telemetry/index.md
+- docs/telemetry/pipelines.md
+- docs/telemetry/review-apps.md
+- docs/telemetry/troubleshooting.md
 - docs/terraform/details.md
 - docs/terraform/example/.controlplane/controlplane.yml
 - docs/terraform/example/.controlplane/templates/app.yml
@@ -284,7 +304,7 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
 post_install_message: |
-  cpflow 5.1.1 installed.
+  cpflow 5.3.0 installed.
 
   If this repository already uses generated cpflow GitHub Actions, update the
   checked-in wrappers so GitHub loads the matching control-plane-flow release tag: