cpflow 4.2.0 → 5.0.0.rc.1

data/lib/command/generate_github_actions.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+require_relative "generator_helpers"
+
+module Command
+  class GithubActionsGenerator < Thor::Group
+    include Thor::Actions
+    include GeneratorHelpers
+
+    argument :staging_branch, type: :string, required: false
+
+    def copy_files
+      relative_paths = generated_files
+      copy_template_files(relative_paths)
+      substitute_template_variables(relative_paths)
+      make_shell_scripts_executable(relative_paths)
+    end
+
+    def self.source_root
+      Cpflow.root_path.join("lib")
+    end
+
+    private
+
+    def copy_template_files(relative_paths)
+      relative_paths.each do |relative_path|
+        empty_directory(File.dirname(relative_path), verbose: false)
+        copy_file(
+          File.join("github_flow_templates", relative_path),
+          relative_path,
+          force: true,
+          verbose: ENV.fetch("HIDE_COMMAND_OUTPUT", nil) != "true"
+        )
+      end
+    end
+
+    def template_variables
+      {
+        "__CPFLOW_VERSION__" => ::Cpflow::VERSION,
+        "__STAGING_BRANCH_FILTER__" => staging_branch_filter,
+        "__STAGING_APP_BRANCH_EXPRESSION__" => staging_app_branch_expression
+      }
+    end
+
+    def generated_files
+      # Keep file discovery centralized on the command class so existence checks and
+      # Thor's template copy list cannot drift.
+      GenerateGithubActions.generated_files
+    end
+
+    def staging_branch_filter
+      branches = staging_branch ? [staging_branch] : %w[main master]
+      # JSON string literals are valid YAML flow-sequence scalars, so this keeps
+      # the generated branch list readable while still escaping branch names.
+      branches.map(&:to_json).join(", ")
+    end
+
+    def staging_app_branch_expression
+      return "${{ vars.STAGING_APP_BRANCH }}" unless staging_branch
+
+      # `valid_staging_branch?` excludes quotes, so this single-quoted GitHub
+      # expression literal cannot be broken by the generated branch name.
+      "${{ vars.STAGING_APP_BRANCH || '#{staging_branch}' }}"
+    end
+  end
+
+  class GenerateGithubActions < Base
+    NAME = "generate-github-actions"
+    OPTIONS = [staging_branch_option].freeze
+    DESCRIPTION = "Creates GitHub Actions templates for review apps, staging deploys, and production promotion"
+    LONG_DESCRIPTION = <<~DESC
+      Creates GitHub Actions templates for a Heroku Flow style Control Plane pipeline:
+      - on-demand review apps for pull requests
+      - automatic staging deploys from your main branch
+      - manual promotion from staging to production
+      - nightly cleanup and PR help workflows
+
+      Pass `--staging-branch BRANCH` when staging should auto-deploy from a branch
+      other than `main` or `master`; the generator will bake that branch into the
+      GitHub Actions push trigger and use it as the default STAGING_APP_BRANCH.
+    DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # Creates .github/actions and .github/workflows files for the Control Plane flow
+      cpflow generate-github-actions
+
+      # Creates the flow with staging deploys triggered from develop
+      cpflow generate-github-actions --staging-branch develop
+      ```
+    EX
+    WITH_INFO_HEADER = false
+    VALIDATIONS = [].freeze
+    REQUIRES_STARTUP_CHECKS = false
+
+    # Resolve template root from __dir__ rather than Cpflow.root_path because this file is
+    # loaded before `module Cpflow` finishes defining its class methods.
+    TEMPLATE_ROOT = Pathname.new(File.expand_path("../github_flow_templates", __dir__))
+
+    def self.generated_files
+      ensure_template_root!
+
+      Dir.glob(TEMPLATE_ROOT.join("**", "*").to_s, File::FNM_DOTMATCH)
+         .select { |path| File.file?(path) }
+         .map { |path| Pathname.new(path).relative_path_from(TEMPLATE_ROOT).to_s }
+         .sort
+         .freeze
+    end
+
+    def self.ensure_template_root!
+      raise "cpflow template directory not found: #{TEMPLATE_ROOT}" unless TEMPLATE_ROOT.directory?
+    end
+
+    def call
+      self.class.ensure_template_root!
+      branch = staging_branch
+
+      if (existing = existing_files).any?
+        files = existing.map { |path| "- #{path}" }.join("\n")
+        Shell.warn("The following files already exist:\n#{files}\n\n" \
+                   "Remove or rename them before running `cpflow #{NAME}` again.")
+        return
+      end
+
+      GithubActionsGenerator.start([branch].compact)
+    end
+
+    private
+
+    def existing_files
+      @existing_files ||= self.class.generated_files.select { |path| File.exist?(path) }
+    end
+
+    def staging_branch
+      branch = config.options[:staging_branch].to_s.strip
+      return nil if branch.empty?
+
+      unless valid_staging_branch?(branch)
+        Shell.abort(
+          "Invalid --staging-branch value: #{branch.inspect}. " \
+          "Use a valid git branch name containing only alphanumerics, dots, slashes, underscores, hyphens, and @."
+        )
+      end
+
+      branch
+    end
+
+    def valid_staging_branch?(branch)
+      return false unless branch.match?(%r{\A[a-zA-Z0-9._/@-]+\z})
+
+      valid_git_branch_shape?(branch) && valid_git_branch_components?(branch)
+    end
+
+    def valid_git_branch_shape?(branch)
+      return false if branch.start_with?("-", "/", ".")
+      return false if branch.end_with?("/", ".")
+      return false if branch.include?("@{")
+
+      !branch.include?("..")
+    end
+
+    def valid_git_branch_components?(branch)
+      branch.split("/").none? do |component|
+        component.empty? || component.start_with?(".") || component.end_with?(".lock")
+      end
+    end
+  end
+end

data/lib/command/generator_helpers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Command
+  module GeneratorHelpers
+    private
+
+    def substitute_template_variables(file_paths, replacements = template_variables)
+      Array(file_paths).each do |path|
+        next unless File.file?(path)
+
+        contents = File.read(path)
+        updated_contents = replacements.reduce(contents) do |memo, (placeholder, value)|
+          # Block form avoids regex-style back-reference interpretation (\1, \&, \\) in `value`.
+          memo.gsub(placeholder) { value }
+        end
+
+        next if updated_contents == contents
+
+        File.write(path, updated_contents)
+      end
+    end
+
+    def make_shell_scripts_executable(file_paths)
+      Array(file_paths).each do |path|
+        next unless File.file?(path) && File.extname(path) == ".sh"
+
+        FileUtils.chmod(0o755, path)
+      end
+    end
+  end
+end

data/lib/command/github_flow_readiness.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Command
+  class GithubFlowReadiness < Base
+    NAME = "github-flow-readiness"
+    DESCRIPTION = "Checks whether the current repo is ready for the Control Plane GitHub flow rollout"
+    LONG_DESCRIPTION = <<~DESC
+      Checks the current repository for common rollout blockers before adding the Control Plane GitHub flow:
+      - Rails runtime scaffold present
+      - modern Ruby and Bundler toolchain
+      - installable exact-pinned direct gem and npm package versions
+      - production Dockerfile presence and SQLite production hints
+    DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # Checks the current repo for common rollout blockers
+      cpflow github-flow-readiness
+      ```
+    EX
+    WITH_INFO_HEADER = false
+    VALIDATIONS = [].freeze
+    REQUIRES_STARTUP_CHECKS = false
+
+    def call
+      service = GithubFlowReadinessService.new
+
+      service.results.each do |result|
+        Shell.info("[#{result.status.to_s.upcase}] #{result.message}")
+      end
+
+      Shell.info("")
+      Shell.info(service.summary)
+
+      exit(ExitCode::ERROR_DEFAULT) if service.blockers?
+    end
+  end
+end

data/lib/command/promote_app_from_upstream.rb

@@ -5,7 +5,8 @@ module Command
     NAME = "promote-app-from-upstream"
     OPTIONS = [
       app_option(required: true),
-      upstream_token_option(required: true)
+      upstream_token_option(required: true),
+      use_digest_image_ref_option
     ].freeze
     DESCRIPTION = "Copies the latest image from upstream, runs a release script (optional), and deploys the image"
     LONG_DESCRIPTION = <<~DESC
@@ -15,6 +16,7 @@ module Command
         - Runs `cpflow deploy-image` to deploy the image
         - If `.controlplane/controlplane.yml` includes the `release_script`, `cpflow deploy-image` will use the `--run-release-phase` option
         - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
+        - If `use_digest_image_ref` is `true` in the `.controlplane/controlplane.yml` file or `--use-digest-image-ref` option is provided, deployed image's reference will include its digest
     DESC
 
     def call
@@ -31,8 +33,17 @@ module Command
 
     def deploy_image
       args = []
-      args.push("--run-release-phase") if config.current[:release_script]
+      args.push("--run-release-phase") if config.current&.dig(:release_script)
+      digest_image_ref_option = deploy_image_digest_ref_option
+      args.push(digest_image_ref_option) if digest_image_ref_option
       run_cpflow_command("deploy-image", "-a", config.app, *args)
     end
+
+    def deploy_image_digest_ref_option
+      # Forward explicit false so a parent CLI override is not lost when the child command re-reads YAML.
+      return "--no-use-digest-image-ref" if config.options[:use_digest_image_ref] == false
+
+      "--use-digest-image-ref" if config.use_digest_image_ref?
+    end
   end
 end

data/lib/command/run.rb

@@ -48,7 +48,7 @@ module Command
       - By default, the job is stopped if it takes longer than 6 hours to finish
         (can be configured though `runner_job_timeout` in `controlplane.yml`)
     DESC
-    EXAMPLES = <<~EX
+    EXAMPLES = <<~EX.freeze
       ```sh
       # Opens shell (bash by default).
       cpflow run -a $APP_NAME

data/lib/command/terraform/generate.rb

@@ -14,6 +14,7 @@ module Command
         - Generates terraform configuration files based on `controlplane.yml` and `templates/` config
       DESC
       WITH_INFO_HEADER = false
+      REQUIRES_STARTUP_CHECKS = false
 
       def call
         Array(config.app || config.apps.keys).each do |app|

data/lib/command/version.rb

@@ -10,6 +10,7 @@ module Command
     DESC
     WITH_INFO_HEADER = false
     VALIDATIONS = [].freeze
+    REQUIRES_STARTUP_CHECKS = false
 
     def call
       puts Cpflow::VERSION

data/lib/constants/exit_code.rb

@@ -2,6 +2,7 @@
 
 module ExitCode
   SUCCESS = 0
+  NOT_FOUND = 3
   ERROR_DEFAULT = 64
   INTERRUPT = 130
 end

data/lib/core/config.rb

@@ -145,6 +145,14 @@ class Config # rubocop:disable Metrics/ClassLength
                                 end&.last
   end
 
+  def use_digest_image_ref?
+    # Three-state: --use-digest-image-ref → true, --no-use-digest-image-ref → false
+    # (both short-circuit YAML), absent → nil (fall through to YAML).
+    return options[:use_digest_image_ref] unless options[:use_digest_image_ref].nil?
+
+    current&.dig(:use_digest_image_ref) == true
+  end
+
   private
 
   def ensure_current_config!

data/lib/core/controlplane.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "shellwords"
+
 class Controlplane # rubocop:disable Metrics/ClassLength
   attr_reader :config, :api, :gvc, :org
 
@@ -93,14 +95,14 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   def image_build(image, dockerfile:, docker_context:, docker_args: [], build_args: [])
     # https://docs.controlplane.com/guides/push-image#step-2
     # Might need to use `docker buildx build` if compatiblitity issues arise
-    cmd = "docker build --platform=linux/amd64 -t #{image} -f #{dockerfile}"
-    cmd += " --progress=plain" if ControlplaneApiDirect.trace
+    cmd = ["docker", "build", "--platform=linux/amd64", "-t", image, "-f", dockerfile]
+    cmd << "--progress=plain" if ControlplaneApiDirect.trace
 
-    cmd += " #{docker_args.join(' ')}" if docker_args.any?
-    build_args.each { |build_arg| cmd += " --build-arg #{build_arg}" }
-    cmd += " #{docker_context}"
+    cmd.concat(docker_args)
+    build_args.each { |build_arg| cmd.concat(["--build-arg", build_arg]) }
+    cmd << docker_context
 
-    perform!(cmd)
+    perform!(Shellwords.join(cmd))
   end
 
   def fetch_image_details(image)
@@ -321,7 +323,7 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   # domain
 
   def find_domain_route(data)
-    port = data["spec"]["ports"].find { |current_port| current_port["number"] == 80 || current_port["number"] == 443 }
+    port = data["spec"]["ports"].find { |current_port| [80, 443].include?(current_port["number"]) }
     return nil if port.nil? || port["routes"].nil?
 
     route = port["routes"].find { |current_route| current_route["prefix"] == "/" }

data/lib/core/controlplane_api_direct.rb

@@ -2,7 +2,7 @@
 
 class RedactedDebugOutput
   SAFE_HEADERS = %w[Content-Type Content-Length Accept Host Date Cache-Control Connection].freeze
-  HEADER_REGEX = /^([A-Za-z\-]+): (.+)$/.freeze
+  HEADER_REGEX = /^([A-Za-z-]+): (.+)$/
 
   def <<(msg)
     $stdout << redact(msg)
@@ -37,7 +37,7 @@ class ControlplaneApiDirect
   #  /^[\w\-._]{1134}$/ # 'cpln profile token' format
   # ).freeze
 
-  API_TOKEN_REGEX = /^[\w\-._]+$/.freeze
+  API_TOKEN_REGEX = /^[\w\-._]+$/
   API_TOKEN_EXPIRY_SECONDS = 300
 
   class << self
@@ -111,7 +111,7 @@ class ControlplaneApiDirect
   def should_refresh_api_token?
     return false unless api_token[:comes_from_profile]
 
-    payload, = JWT.decode(api_token[:token], nil, false)
+    payload, = JWT.decode(api_token[:token], nil, false, algorithms: [])
     difference_in_seconds = payload["exp"] - Time.now.to_i
 
     difference_in_seconds <= API_TOKEN_EXPIRY_SECONDS

data/lib/core/github_flow_readiness/checks.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module GithubFlowReadiness
+  Result = Struct.new(:status, :message, keyword_init: true)
+
+  # Each check class accepts the host service in its initializer (so it can reach the
+  # shared lockfile parser, HTTP version cache, etc.), exposes a single `call` method,
+  # and returns either a `Result`, an array of `Result`s, or `nil` (skipped). Adding
+  # a new check is "create a class with `call` and register it in
+  # `GithubFlowReadinessService::CHECKS`".
+  module Checks
+    class Base
+      def initialize(service)
+        @service = service
+      end
+
+      private
+
+      attr_reader :service
+
+      def root_path
+        service.root_path
+      end
+
+      def pass(message)
+        Result.new(status: :pass, message: message)
+      end
+
+      def fail_result(message)
+        Result.new(status: :fail, message: message)
+      end
+
+      def warn_result(message)
+        Result.new(status: :warn, message: message)
+      end
+
+      def info_result(message)
+        Result.new(status: :info, message: message)
+      end
+
+      def format_path_list(paths)
+        paths.map { |path| "`#{path}`" }.join(", ")
+      end
+
+      def first_existing_path(paths)
+        paths.find { |relative_path| root_path.join(relative_path).file? }
+      end
+
+      def missing_paths_for(paths)
+        paths.reject { |relative_path| root_path.join(relative_path).file? }
+      end
+    end
+
+    class RailsApp < Base
+      REQUIRED_PATHS = ["Gemfile", "bin/rails", "config/application.rb", "config.ru"].freeze
+
+      def call
+        missing = missing_paths_for(REQUIRED_PATHS)
+        return pass("Rails app scaffold found (#{format_path_list(REQUIRED_PATHS)}).") if missing.empty?
+
+        fail_result("Missing Rails runtime scaffold: #{format_path_list(missing)}.")
+      end
+    end
+
+    class RubyVersion < Base
+      # Oldest Ruby line still receiving security backports (ruby-lang.org/en/downloads/branches/).
+      # Bump this constant when the upstream list drops the 3.3 series.
+      THRESHOLD = Gem::Version.new("3.3.0")
+
+      def call
+        version = service.inferred_ruby_version
+        return warn_result("Could not determine the app Ruby version.") unless version
+        return pass("Ruby #{version} is modern enough for rollout.") if version >= THRESHOLD
+
+        fail_result("Ruby #{version} is legacy. Upgrade the repo toolchain before adding the GitHub flow.")
+      end
+    end
+
+    class BundlerVersion < Base
+      THRESHOLD = Gem::Version.new("2.0.0")
+
+      def call
+        version = service.lockfile_bundler_version
+        return warn_result("Could not determine the Bundler version from `Gemfile.lock`.") unless version
+        return pass("Bundler #{version} is modern enough for rollout.") if version >= THRESHOLD
+
+        fail_result("Bundler #{version} is legacy. Upgrade the repo toolchain before adding the GitHub flow.")
+      end
+    end
+
+    class Dockerfile < Base
+      PATHS = ["Dockerfile", ".controlplane/Dockerfile"].freeze
+
+      def call
+        path = first_existing_path(PATHS)
+        return pass("Found production Dockerfile at `#{path}`.") if path
+
+        fail_result(
+          "No production Dockerfile found at `Dockerfile` or `.controlplane/Dockerfile`. " \
+          "Add and validate one before generating the Control Plane GitHub flow."
+        )
+      end
+    end
+
+    class SqliteProduction < Base
+      def call
+        return unless service.sqlite_database_in_production?
+
+        info_result(
+          "Production database config uses SQLite. `cpflow generate` will scaffold " \
+          "persistent `db` and `storage` volumes."
+        )
+      end
+    end
+
+    class GemSources < Base
+      def call
+        non_public = service.gem_dependencies.reject { |dep| service.public_rubygems_dependency?(dep) }
+        return pass("All direct Ruby gems resolve from public RubyGems sources.") if non_public.empty?
+
+        names = non_public.map { |dep| dep[:name] }.sort
+        warn_result(
+          "Direct Ruby dependencies using git/path or non-public gem sources need manual review: " \
+          "#{names.map { |name| "`#{name}`" }.join(', ')}."
+        )
+      end
+    end
+
+    class GemExactPins < Base
+      def call
+        service.exact_pin_registry_result(service.rubygems_registry_check)
+      end
+    end
+
+    class NpmExactPins < Base
+      def call
+        return service.package_json_parse_error_result if service.package_json_parse_error
+
+        service.exact_pin_registry_result(service.npm_registry_check)
+      end
+    end
+  end
+end