cpflow 5.3.0 → 6.0.0

data/lib/command/update_github_actions.rb

@@ -5,32 +5,49 @@ require "yaml"
 require_relative "staging_branch_validation"
 
 module Command
-  class UpdateGithubActions < Base
+  class UpdateGithubActions < Base # rubocop:disable Metrics/ClassLength
     include StagingBranchValidation
 
     NAME = "update-github-actions"
-    OPTIONS = [staging_branch_option].freeze
-    DESCRIPTION = "Regenerates generated GitHub Actions wrappers for the installed cpflow version"
+    OPTIONS = [staging_branch_option, {
+      name: :workflows,
+      params: {
+        type: :array, banner: "FILE...",
+        desc: "Explicitly add or replace these generated workflow filenames (default: preserve all workflows)"
+      }
+    }].freeze
+    DESCRIPTION = "Regenerates GitHub Actions files for the installed cpflow version"
     LONG_DESCRIPTION = <<~DESC.freeze
-      Regenerates the generated cpflow GitHub Actions wrappers and helper files
-      from the currently installed cpflow gem. Use this after updating the
-      cpflow gem so checked-in workflow wrappers move to the matching upstream
-      release tag, for example `v#{Cpflow::VERSION}`.
-
-      If the existing generated staging workflow uses a custom single staging
-      branch, the command preserves it. Pass `--staging-branch BRANCH` to set or
-      replace the generated staging branch explicitly.
+      Refreshes local composite actions and helper files from the installed gem.
+      All top-level workflows are preserved by default, including their refs,
+      triggers, permissions, and deployment ownership. Use --workflows FILE...
+      to explicitly add or replace named generated workflows. Replacement resets
+      each selected workflow to its template and matching v#{Cpflow::VERSION} ref;
+      review and reapply any downstream customizations in the same PR.
+
+      Selecting cpflow-deploy-staging.yml preserves a single existing push branch
+      or the default main/master pair. Missing or ambiguous branches require
+      --staging-branch BRANCH. This option requires selecting the staging workflow.
+
+      A differing existing bin/test-cpflow-github-flow blocks all writes. Move
+      downstream checks to executable bin/test-cpflow-github-flow-custom and
+      remove or rename the old validator before updating. The generated validator
+      invokes that extension after its baseline checks; the extension is never
+      generated or overwritten. See docs/ci-automation.md for migration guidance.
     DESC
     EXAMPLES = <<~EX
       ```sh
-      # After updating the cpflow gem, refresh generated GitHub Actions wrappers
+      # Refresh actions/helpers while preserving downstream workflows
       cpflow update-github-actions
 
       # When running cpflow through Bundler
       bundle exec cpflow update-github-actions
 
-      # Preserve or set a custom staging branch
-      cpflow update-github-actions --staging-branch develop
+      # Explicitly replace the review-app wrapper
+      cpflow update-github-actions --workflows cpflow-deploy-review-app.yml
+
+      # Explicitly add or replace staging deployment from develop
+      cpflow update-github-actions --workflows cpflow-deploy-staging.yml --staging-branch develop
       ```
     EX
     WITH_INFO_HEADER = false
@@ -43,66 +60,88 @@ module Command
     def call
       GenerateGithubActions.ensure_template_root!
       abort_if_no_generated_files!
-
-      branch = staging_branch || inferred_staging_branch
-      GithubActionsGenerator.start([branch].compact)
+      workflows = selected_workflows
+      branch = selected_staging_branch(workflows)
+      abort_if_custom_validator!
+      GithubActionsGenerator.new([branch].compact, workflows: workflows).invoke_all
 
       print_post_update_message
     end
 
     private
 
+    def selected_workflows
+      available = GenerateGithubActions.generated_files.grep(%r{\A\.github/workflows/}).map do |path|
+        File.basename(path)
+      end
+      selected = Array(config.options[:workflows])
+      unknown = selected - available
+      Shell.abort("Unknown --workflows: #{unknown.join(', ')}. Available: #{available.join(', ')}") if unknown.any?
+      selected
+    end
+
+    def selected_staging_branch(workflows)
+      branch = staging_branch
+      return branch || inferred_staging_branch if workflows.include?(STAGING_WORKFLOW_PATH.basename.to_s)
+
+      Shell.abort("--staging-branch requires --workflows cpflow-deploy-staging.yml") if branch
+      nil
+    end
+
+    def abort_if_custom_validator!
+      path = "bin/test-cpflow-github-flow"
+      return unless File.exist?(path)
+      return if File.binread(path) == File.binread(GenerateGithubActions.source_file(path))
+
+      Shell.abort(<<~MESSAGE)
+        #{path} differs from the current generated validator. No files were updated.
+        Move downstream checks to executable bin/test-cpflow-github-flow-custom, then remove or rename
+        #{path} and retry. See docs/ci-automation.md for the legacy validator migration.
+      MESSAGE
+    end
+
     def abort_if_no_generated_files!
       return if GenerateGithubActions.generated_files.any? { |path| File.exist?(path) }
 
-      Shell.abort(
-        "No generated cpflow GitHub Actions files found in this repository. " \
-        "Run `cpflow generate-github-actions` first to create the wrappers, " \
-        "then use `cpflow update-github-actions` after future gem upgrades."
-      )
+      Shell.abort(<<~MESSAGE)
+        No generated cpflow GitHub Actions files found in this repository.
+        Run `cpflow generate-github-actions` first to create the wrappers,
+        then use `cpflow update-github-actions` after future gem upgrades.
+      MESSAGE
     end
 
     def print_post_update_message
       Shell.info("")
-      Shell.info("Updated cpflow GitHub Actions wrappers for cpflow #{Cpflow::VERSION}.")
+      Shell.info("Updated cpflow GitHub Actions files for cpflow #{Cpflow::VERSION}.")
+      Shell.info("Preserved unselected workflows; review their refs and compatibility before committing.")
       Shell.info("Next: review the diff and run `bin/test-cpflow-github-flow`.")
       Shell.info("If you run cpflow through Bundler, use `bin/test-cpflow-github-flow bundle exec cpflow`.")
     end
 
     def inferred_staging_branch
       branches = existing_staging_branches
-      return if branches.empty? || branches.sort == DEFAULT_STAGING_BRANCHES.sort
-      return branches.first if branches.length == 1
-
-      Shell.warn(
-        "Existing staging workflow has multiple custom push branches: #{branches.join(', ')}. " \
-        "Run with --staging-branch BRANCH if only one branch should auto-deploy staging."
-      )
+      return if branches.sort == DEFAULT_STAGING_BRANCHES.sort
+      return branches.first if branches.length == 1 && valid_staging_branch?(branches.first)
 
-      nil
+      Shell.abort("Cannot infer staging deployment branch. Pass --staging-branch BRANCH to explicitly set it.")
     end
 
     def existing_staging_branches
-      Array(parsed_staging_workflow_on.dig("push", "branches")).map(&:to_s)
+      push = parsed_staging_workflow_on["push"]
+      branches = push.is_a?(Hash) ? push["branches"] : nil
+      branches.is_a?(Array) && branches.all?(String) ? branches : []
     end
 
     def parsed_staging_workflow_on
       return {} unless STAGING_WORKFLOW_PATH.file?
 
       workflow = YAML.load_file(STAGING_WORKFLOW_PATH, aliases: true)
-      return {} unless workflow.is_a?(Hash)
-
-      workflow_on = workflow["on"] || workflow[true]
+      workflow_on = workflow.is_a?(Hash) ? workflow["on"] || workflow[true] : nil
       workflow_on.is_a?(Hash) ? workflow_on : {}
     rescue Psych::SyntaxError => e
-      warn_unparseable_staging_workflow(e)
-      {}
-    end
-
-    def warn_unparseable_staging_workflow(error)
-      Shell.warn(
-        "Could not parse #{STAGING_WORKFLOW_PATH}: #{error.message}. " \
-        "Run with --staging-branch BRANCH if staging should use a custom branch."
+      Shell.abort(
+        "Could not parse #{STAGING_WORKFLOW_PATH}: #{e.message}. " \
+        "Pass --staging-branch BRANCH to explicitly replace its staging deployment branch."
       )
     end
   end

data/lib/core/config.rb

@@ -10,6 +10,7 @@ class Config # rubocop:disable Metrics/ClassLength
   include Helpers
 
   CONFIG_FILE_LOCATION = ".controlplane/controlplane.yml"
+  GENERATED_REVIEW_APP_TAG = "cpflow-generated-review-app"
   REQUIRED_SHARED_SECRET_GRANT_KEYS = %i[name secret_name policy_name].freeze
   SHARED_SECRET_RESOURCE_NAME_KEYS = %i[secret_name policy_name].freeze
   CONTROL_PLANE_RESOURCE_NAME_REGEX = /\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/
@@ -52,6 +53,8 @@ class Config # rubocop:disable Metrics/ClassLength
   end
 
   def secrets
+    return "#{app}-secrets" if generated_review_secret_keys.any?
+
     current&.dig(:secrets_name) || "#{app_prefix}-secrets"
   end
 
@@ -59,6 +62,54 @@ class Config # rubocop:disable Metrics/ClassLength
     current&.dig(:secrets_policy_name) || "#{secrets}-policy"
   end
 
+  def generated_review_secret_keys
+    @generated_review_secret_keys ||= begin
+      keys = current&.dig(:generated_review_secret_keys)
+      if keys.nil?
+        []
+      else
+        validate_generated_review_secret_scope!
+        validate_generated_review_secret_keys!(keys)
+        keys
+      end
+    end
+  end
+
+  # Cleanup must still find marked per-app resources after the opt-in is removed
+  # from the current configuration.
+  def disposable_review_secret_resource_names
+    return nil unless current&.dig(:match_if_app_name_starts_with) && app.to_s != app_prefix.to_s
+    return nil unless app.match?(CONTROL_PLANE_RESOURCE_NAME_REGEX)
+
+    secret = "#{app}-secrets"
+    policy = "#{secret}-policy"
+    return nil unless policy.length <= 64
+
+    [secret, policy]
+  end
+
+  def validate_generated_review_secret_scope!
+    dynamic_review_app = current[:match_if_app_name_starts_with] && app.to_s != app_prefix.to_s
+    raise "generated_review_secret_keys is only allowed for a dynamically named review app." unless dynamic_review_app
+
+    unless "#{app}-secrets-policy".length <= 64 && app.match?(CONTROL_PLANE_RESOURCE_NAME_REGEX)
+      raise "Review app name is too long or invalid for a per-app secret policy."
+    end
+    return unless current[:secrets_name] || current[:secrets_policy_name]
+
+    raise "generated_review_secret_keys cannot be combined with secrets_name or secrets_policy_name."
+  end
+
+  def validate_generated_review_secret_keys!(keys)
+    valid_size = keys.is_a?(Array) && keys.size.between?(1, 8)
+    valid_names = valid_size && keys.all? { |key| key.is_a?(String) && key.match?(/\A[A-Z][A-Z0-9_]*\z/) }
+    return if valid_names && keys.uniq == keys
+
+    raise "generated_review_secret_keys must contain 1-8 unique uppercase environment names."
+  end
+
+  private :validate_generated_review_secret_scope!, :validate_generated_review_secret_keys!
+
   def shared_secret_grants
     @shared_secret_grants ||= normalize_shared_secret_grants(current&.dig(:shared_secret_grants))
   end
@@ -188,6 +239,28 @@ class Config # rubocop:disable Metrics/ClassLength
     end
   end
 
+  def validate_generated_review_secret_settings!
+    apps.each do |app_name, app_options|
+      keys = app_options[:generated_review_secret_keys]
+      next if keys.nil?
+
+      validate_generated_review_secret_entry_scope!(app_name, app_options)
+      validate_generated_review_secret_keys!(keys)
+    end
+  end
+
+  def validate_generated_review_secret_entry_scope!(app_name, app_options)
+    unless app_options[:match_if_app_name_starts_with]
+      raise "generated_review_secret_keys for '#{app_name}' requires a dynamically matched review app."
+    end
+    return unless app_options[:secrets_name] || app_options[:secrets_policy_name]
+
+    raise "generated_review_secret_keys for '#{app_name}' cannot be combined with " \
+          "secrets_name or secrets_policy_name."
+  end
+
+  private :validate_generated_review_secret_entry_scope!
+
   private
 
   def ensure_current_config!