flow_chat 0.8.2 → 0.9.0

data/lib/flow_chat/whatsapp/id_generator.rb

@@ -0,0 +1,124 @@
+require "digest"
+
+module FlowChat
+  module Whatsapp
+    # Generates WhatsApp-safe IDs from choice labels
+    #
+    # WhatsApp Cloud API requires button and list item IDs to be:
+    # - Maximum 256 characters
+    # - Unique within the message
+    # - Non-empty strings
+    #
+    # This generator:
+    # - Sanitizes labels to alphanumeric + underscore/hyphen
+    # - Truncates to fit within 256-char limit
+    # - Appends hash suffix for duplicate labels (similar to Rails index naming)
+    # - Ensures readability while maintaining uniqueness
+    #
+    # @example Basic usage
+    #   generator = IdGenerator.new
+    #   id = generator.generate_id("Create Account")  # => "create_account"
+    #
+    # @example Handling duplicates
+    #   generator = IdGenerator.new
+    #   id1 = generator.generate_id("Accept")  # => "accept"
+    #   id2 = generator.generate_id("Accept")  # => "accept_a1b2c3"
+    #
+    # @example Special characters
+    #   generator = IdGenerator.new
+    #   id = generator.generate_id("Yes! 👍 (recommended)")  # => "yes_recommended"
+    #
+    class IdGenerator
+      MAX_ID_LENGTH = 256
+      HASH_SUFFIX_LENGTH = 3
+
+      def initialize
+        @generated_ids = []
+      end
+
+      # Generate a WhatsApp-safe ID from a label
+      #
+      # @param label [String] The choice label to convert
+      # @return [String] A sanitized, unique ID
+      def generate_id(label)
+        # Normalize the label
+        normalized = normalize_label(label)
+
+        # If normalized label is empty, use a fallback
+        normalized = "choice" if normalized.empty?
+
+        # Truncate to limit first
+        truncated = truncate_to_limit(normalized)
+
+        # Check if we need a hash suffix for uniqueness
+        final_id = if @generated_ids.include?(truncated)
+          add_hash_suffix(truncated, label)
+        else
+          truncated
+        end
+
+        # Track this ID
+        @generated_ids << final_id
+
+        final_id
+      end
+
+      # Reset the generator state (useful for testing or starting a new message)
+      def reset
+        @generated_ids = []
+      end
+
+      # Get all generated IDs (useful for debugging)
+      def generated_ids
+        @generated_ids.dup
+      end
+
+      private
+
+      # Normalize a label into a WhatsApp-safe identifier
+      # Keeps readability by preserving spaces and basic punctuation
+      #
+      # @param label [String] The original label
+      # @return [String] Normalized identifier
+      def normalize_label(label)
+        label
+          .to_s
+          .gsub(/[^\w\s\-']/, "")        # remove special chars (keep word chars, spaces, hyphens, apostrophes)
+          .gsub(/\s+/, " ")              # collapse multiple spaces to single space (after removing chars)
+          .strip                          # trim leading/trailing whitespace
+      end
+
+      # Add a hash suffix to make the ID unique
+      #
+      # The hash is generated from the original label to ensure
+      # the same label always produces the same hash.
+      #
+      # @param base_id [String] The base identifier
+      # @param original_label [String] The original label for hash generation
+      # @return [String] ID with hash suffix
+      def add_hash_suffix(base_id, original_label)
+        # Generate a short hash from the original label + timestamp for uniqueness
+        # We use the current generated_ids count to ensure different duplicates get different hashes
+        hash_input = "#{original_label}_#{@generated_ids.count { |id| id.start_with?(base_id) }}"
+        hash = Digest::SHA256.hexdigest(hash_input)[0...HASH_SUFFIX_LENGTH]
+
+        # Calculate max base length to fit: base + "_" + hash
+        max_base_length = MAX_ID_LENGTH - HASH_SUFFIX_LENGTH - 1
+
+        # Truncate base if needed
+        truncated_base = base_id[0...max_base_length]
+
+        "#{truncated_base} #{hash}"
+      end
+
+      # Truncate ID to maximum allowed length
+      #
+      # @param id [String] The ID to truncate
+      # @return [String] Truncated ID
+      def truncate_to_limit(id)
+        return id if id.length <= MAX_ID_LENGTH
+        id[0...MAX_ID_LENGTH]
+      end
+    end
+  end
+end

data/lib/flow_chat/whatsapp/middleware/choice_mapper.rb

@@ -0,0 +1,147 @@
+require_relative "../id_generator"
+
+module FlowChat
+  module Whatsapp
+    module Middleware
+      # Maps WhatsApp button/list IDs back to original choice keys
+      #
+      # Similar to USSD::ChoiceMapper, but for WhatsApp interactive messages.
+      # WhatsApp uses generated IDs (from IdGenerator) for buttons and list items,
+      # and this middleware maps the user's response back to the original choice key.
+      #
+      # Flow:
+      # 1. Flow returns choices with original keys (e.g., {"create" => "Create Account"})
+      # 2. Middleware generates WhatsApp-safe IDs from labels
+      # 3. Middleware transforms choices to use generated IDs as keys
+      # 4. Middleware stores mapping (generated_id → original_key)
+      # 5. Renderer receives transformed choices and renders them
+      # 6. User selects a button/list item (WhatsApp sends the ID)
+      # 7. This middleware intercepts and replaces ID with original key
+      # 8. Flow sees the original choice key (not the generated ID)
+      #
+      # @example
+      #   # Flow provides: {"create" => "Create Account"}
+      #   # Middleware generates ID: "Create Account"
+      #   # Middleware transforms to: {"Create Account" => "Create Account"}
+      #   # Middleware stores: {"Create Account" => "create"}
+      #   # User clicks, WhatsApp sends: "Create Account"
+      #   # Middleware intercepts and maps back to: "create"
+      #
+      #   # With duplicates: {"yes" => "Accept", "no" => "Accept"}
+      #   # IDs generated: "Accept", "Accept 3a4"
+      #   # Transformed: {"Accept" => "Accept", "Accept 3a4" => "Accept"}
+      #   # Mapping: {"Accept" => "yes", "Accept 3a4" => "no"}
+      #   # User clicks second, WhatsApp sends: "Accept 3a4"
+      #   # Middleware maps back to: "no"
+      #
+      class ChoiceMapper
+        def initialize(app)
+          @app = app
+          FlowChat.logger.debug { "Whatsapp::ChoiceMapper: Initialized WhatsApp choice mapping middleware" }
+        end
+
+        def call(context)
+          @context = context
+          @session = context.session
+
+          session_id = context["session.id"]
+          FlowChat.logger.debug { "Whatsapp::ChoiceMapper: Processing request for session #{session_id}" }
+
+          if intercept?
+            FlowChat.logger.info { "Whatsapp::ChoiceMapper: Intercepting request for choice resolution - session #{session_id}" }
+            handle_choice_input
+          end
+
+          # Clear choice mapping state for new flows
+          clear_choice_state_if_needed
+
+          # Call the app (executor -> flow)
+          type, prompt, choices, media = @app.call(context)
+
+          # Transform choices if present (like USSD does)
+          if choices.present?
+            FlowChat.logger.debug { "Whatsapp::ChoiceMapper: Found choices, creating ID mapping" }
+            choices = create_id_mapping(choices)
+          end
+
+          [type, prompt, choices, media]
+        end
+
+        private
+
+        def intercept?
+          # Intercept if we have choice mapping state and user input matches a generated ID
+          choice_mapping = get_choice_mapping
+          should_intercept = choice_mapping.present? &&
+            @context.input.present? &&
+            choice_mapping.key?(@context.input.to_s)
+
+          if should_intercept
+            FlowChat.logger.debug { "Whatsapp::ChoiceMapper: Intercepting - input: #{@context.input}, mapped to: #{choice_mapping[@context.input.to_s]}" }
+          end
+
+          should_intercept
+        end
+
+        def handle_choice_input
+          choice_mapping = get_choice_mapping
+          original_choice = choice_mapping[@context.input.to_s]
+
+          FlowChat.logger.info { "Whatsapp::ChoiceMapper: Resolving choice input #{@context.input} to #{original_choice}" }
+
+          # Replace the generated ID with the original choice key
+          @context.input = original_choice
+        end
+
+        def create_id_mapping(choices)
+          # Choices are always a hash after normalize_choices
+          id_generator = IdGenerator.new
+          id_choices = {}
+          choice_mapping = {}
+
+          choices.each do |key, value|
+            # Generate WhatsApp-safe ID from the label
+            generated_id = id_generator.generate_id(value.to_s)
+            id_choices[generated_id] = value
+            choice_mapping[generated_id] = key.to_s
+          end
+
+          store_choice_mapping(choice_mapping)
+          FlowChat.logger.debug { "Whatsapp::ChoiceMapper: Created mapping: #{choice_mapping}" }
+          id_choices
+        end
+
+        def store_choice_mapping(mapping)
+          @session.set("whatsapp.choice_mapping", mapping)
+          FlowChat.logger.debug { "Whatsapp::ChoiceMapper: Stored choice mapping: #{mapping}" }
+        end
+
+        def get_choice_mapping
+          @session.get("whatsapp.choice_mapping") || {}
+        end
+
+        def clear_choice_mapping
+          @session.delete("whatsapp.choice_mapping")
+          FlowChat.logger.debug { "Whatsapp::ChoiceMapper: Cleared choice mapping" }
+        end
+
+        def clear_choice_state_if_needed
+          # Clear choice mapping if this is a new flow (no input or fresh start)
+          if @context.input.blank? || should_clear_for_new_flow?
+            clear_choice_mapping
+          end
+        end
+
+        def should_clear_for_new_flow?
+          # Clear mapping if this input doesn't match any stored mapping
+          # This indicates we're in a new flow step
+          choice_mapping = get_choice_mapping
+          return false if choice_mapping.empty?
+
+          # If input is present but doesn't match any mapping, we're in a new flow
+          @context.input.present? && !choice_mapping.key?(@context.input.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/whatsapp/renderer.rb

@@ -1,6 +1,10 @@
+require "flow_chat/renderers/markdown_support"
+
 module FlowChat
   module Whatsapp
     class Renderer
+      include FlowChat::Renderers::MarkdownSupport
+
       attr_reader :message, :choices, :media
 
       def initialize(message, choices: nil, media: nil)
@@ -24,25 +28,60 @@ module FlowChat
       private
 
       def build_text_message
-        [:text, message, {}]
+        [:text, to_whatsapp(message), {}]
+      end
+
+      def formatted_message
+        to_whatsapp(message)
+      end
+
+      def formatted_caption
+        message.present? ? to_whatsapp(message) : nil
       end
 
       def build_media_message
         media_type = media[:type] || :image
-        url = media[:url] || media[:path]
+        url = media[:url]
+        id = media[:id]
         filename = media[:filename]
 
         case media_type.to_sym
         when :image
-          [:media_image, "", {url: url, caption: message}]
+          options = {}
+          options[:url] = url if url
+          options[:id] = id if id
+          options[:caption] = formatted_caption if formatted_caption
+          [:media_image, "", options]
         when :document
-          [:media_document, "", {url: url, caption: message, filename: filename}]
+          options = {}
+          options[:url] = url if url
+          options[:id] = id if id
+          options[:caption] = formatted_caption if formatted_caption
+          options[:filename] = filename if filename
+          [:media_document, "", options]
         when :audio
-          [:media_audio, "", {url: url, caption: message}]
+          options = {}
+          options[:url] = url if url
+          options[:id] = id if id
+          options[:caption] = formatted_caption if formatted_caption
+          [:media_audio, "", options]
         when :video
-          [:media_video, "", {url: url, caption: message}]
+          options = {}
+          options[:url] = url if url
+          options[:id] = id if id
+          options[:caption] = formatted_caption if formatted_caption
+          [:media_video, "", options]
         when :sticker
-          [:media_sticker, "", {url: url}] # Stickers don't support captions
+          options = {}
+          options[:url] = url if url
+          options[:id] = id if id
+          [:media_sticker, "", options] # Stickers don't support captions
+        when :template
+          [:template, "", {
+            template_name: media[:template_name],
+            components: media[:components] || [],
+            language: media[:language] || "en_US"
+          }]
         else
           raise ArgumentError, "Unsupported media type: #{media_type}"
         end
@@ -86,7 +125,7 @@ module FlowChat
           }
         end
 
-        [:interactive_buttons, message, {buttons: buttons}]
+        [:interactive_buttons, formatted_message, {buttons: buttons}]
       end
 
       def build_buttons_message_with_media(choices)
@@ -100,12 +139,12 @@ module FlowChat
         # Build media header
         header = build_media_header
 
-        [:interactive_buttons, message, {buttons: buttons, header: header}]
+        [:interactive_buttons, formatted_message, {buttons: buttons, header: header}]
       end
 
       def build_media_header
         media_type = media[:type] || :image
-        url = media[:url] || media[:path]
+        url = media[:url]
         filename = media[:filename]
 
         case media_type.to_sym
@@ -174,13 +213,108 @@ module FlowChat
           end
         end
 
-        [:interactive_list, message, {sections: sections}]
+        [:interactive_list, formatted_message, {sections: sections}]
       end
 
       def truncate_text(text, length)
         return text if text.length <= length
         text[0, length - 3] + "..."
       end
+
+      # Convert text to WhatsApp format
+      # Processes markdown through HTML, then converts HTML tags to WhatsApp syntax
+      def to_whatsapp(text)
+        return "" if text.nil?
+
+        # Pre-process: handle markdown features not supported by standard kramdown
+        processed = preprocess_markdown(text.to_s)
+
+        # Convert markdown to HTML
+        html = Kramdown::Document.new(processed, **kramdown_options).to_html.strip
+        html_to_whatsapp(html)
+      end
+
+      # Handle markdown features not natively supported by kramdown
+      def preprocess_markdown(text)
+        result = text.dup
+
+        # Convert fenced code blocks to indented code blocks (kramdown native format)
+        # ```lang\ncode\n``` → indented with 4 spaces
+        result.gsub!(/^```\w*\n(.*?)^```/m) do
+          code = $1
+          code.lines.map { |line| "    #{line}" }.join
+        end
+
+        # Convert ~~strikethrough~~ to HTML <del> tags (kramdown will pass through)
+        result.gsub!(/~~([^~]+)~~/, '<del>\1</del>')
+
+        result
+      end
+
+      # Convert HTML to WhatsApp formatting syntax
+      def html_to_whatsapp(html)
+        result = html.dup
+
+        # Convert code blocks first (before inline code)
+        # <pre><code>...</code></pre> → ```...```
+        result.gsub!(%r{<pre[^>]*><code[^>]*>(.*?)</code></pre>}m) { "```#{$1}```" }
+
+        # Convert inline code: <code>...</code> → `...`
+        result.gsub!(%r{<code[^>]*>(.*?)</code>}m) { "`#{$1}`" }
+
+        # Convert bold: <strong>...</strong> or <b>...</b> → *...*
+        result.gsub!(%r{<(?:strong|b)[^>]*>(.*?)</(?:strong|b)>}m) { "*#{$1}*" }
+
+        # Convert italic: <em>...</em> or <i>...</i> → _..._
+        result.gsub!(%r{<(?:em|i)[^>]*>(.*?)</(?:em|i)>}m) { "_#{$1}_" }
+
+        # Convert strikethrough: <s>...</s>, <del>...</del>, <strike>...</strike> → ~...~
+        result.gsub!(%r{<(?:s|del|strike)[^>]*>(.*?)</(?:s|del|strike)>}m) { "~#{$1}~" }
+
+        # Convert paragraphs to double newlines
+        result.gsub!(%r{<p[^>]*>(.*?)</p>}m) { "#{$1}\n\n" }
+
+        # Convert line breaks
+        result.gsub!(/<br\s*\/?>/, "\n")
+
+        # Convert links: <a href="url">text</a> → text (url)
+        # WhatsApp auto-links URLs, so we just show text and URL
+        result.gsub!(%r{<a[^>]*href=["']([^"']+)["'][^>]*>(.*?)</a>}m) do
+          url, text = $1, $2
+          (text == url) ? url : "#{text} (#{url})"
+        end
+
+        # Convert blockquotes (WhatsApp doesn't have native support, use > prefix)
+        result.gsub!(%r{<blockquote[^>]*>(.*?)</blockquote>}m) do
+          $1.lines.map { |line| "> #{line.strip}" }.join("\n")
+        end
+
+        # Convert lists
+        result.gsub!(%r{<ul[^>]*>(.*?)</ul>}m) do
+          items = $1.scan(%r{<li[^>]*>(.*?)</li>}m).flatten
+          items.map { |item| "• #{item.strip}" }.join("\n")
+        end
+        result.gsub!(%r{<ol[^>]*>(.*?)</ol>}m) do
+          items = $1.scan(%r{<li[^>]*>(.*?)</li>}m).flatten
+          items.map.with_index(1) { |item, i| "#{i}. #{item.strip}" }.join("\n")
+        end
+
+        # Strip any remaining HTML tags
+        result.gsub!(/<[^>]+>/, "")
+
+        # Decode HTML entities
+        result.gsub!("&amp;", "&")
+        result.gsub!("&lt;", "<")
+        result.gsub!("&gt;", ">")
+        result.gsub!("&quot;", '"')
+        result.gsub!("&#39;", "'")
+        result.gsub!("&nbsp;", " ")
+
+        # Clean up excessive newlines
+        result.gsub!(/\n{3,}/, "\n\n")
+
+        result.strip
+      end
     end
   end
 end

data/lib/flow_chat.rb

@@ -10,6 +10,16 @@ loader.enable_reloading if defined?(Rails.env) && Rails.env.development?
 loader.setup
 
 module FlowChat
+  # Special input markers for non-text message types
+  module Input
+    LOCATION = "$location$"
+    MEDIA = "$media$"
+    CONTACT = "$contact$"
+
+    # Session markers
+    START = "$start$"
+  end
+
   def self.root
     Pathname.new __dir__
   end
@@ -26,4 +36,4 @@ module FlowChat
   def self.metrics
     FlowChat::Instrumentation::Setup.metrics_collector
   end
-end
+end

data/lib/tasks/release.rake

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# Release flow
+# ------------
+# Publishing happens from a laptop. CI does NOT push to any registry — it only
+# cuts the GitHub Release (with notes + the built gem) when the tag lands.
+#
+#   1. rake release:prepare          # auto-computes next version via git-cliff
+#      rake release:prepare[1.2.3]   # ...or pass one explicitly
+#                                    # → bumps + regenerates changelog, STAGES
+#                                    #   the changes, and shows the diff. Nothing
+#                                    #   is committed.
+#   2. git diff --cached             # review the staged changes
+#   3. rake release:publish          # commits, publishes the gem, then tags + pushes
+#                                    #   → CI cuts the Release from the tag
+#
+# To abort after prepare: git reset --hard (discards the staged changes).
+# release:publish is idempotent and resumable: it skips a gem already live and
+# only tags if the tag is missing, so a partial failure can just be re-run.
+
+RELEASE_CLIFF_CONFIG = ".cliff.toml"
+RELEASE_VERSION_FILE = "lib/flow_chat/version.rb"
+RELEASE_GEM_NAME = "flow_chat"
+RELEASE_SECURITY_FILE = "SECURITY.md"
+
+namespace :release do
+  # --- helpers --------------------------------------------------------------
+
+  def current_version
+    File.read(RELEASE_VERSION_FILE)[/VERSION = "([\d.]+)"/, 1] ||
+      abort("Could not read VERSION from #{RELEASE_VERSION_FILE}")
+  end
+
+  def git_cliff?
+    system("which git-cliff > /dev/null 2>&1")
+  end
+
+  # Next version per conventional commits. git-cliff owns the semver math
+  # (including the pre-1.0 rules configured under [bump] in .cliff.toml).
+  def computed_next_version
+    abort "git-cliff not found. Install with: brew install git-cliff" unless git_cliff?
+    bumped = `git-cliff --config #{RELEASE_CLIFF_CONFIG} --bumped-version 2>/dev/null`.strip
+    abort "git-cliff could not compute a version (no conventional commits since last tag?)" if bumped.empty?
+    bumped.delete_prefix("v")
+  end
+
+  def gem_published?(version)
+    out = `gem list --remote --exact --all #{RELEASE_GEM_NAME} 2>/dev/null`
+    out.include?("#{version},") || out.include?("#{version})") || out.include?(" #{version} ")
+  end
+
+  # --- version --------------------------------------------------------------
+
+  desc "Show the next version computed from conventional commits"
+  task :version do
+    puts "Current version: #{current_version}"
+    puts "Next version:    #{computed_next_version}"
+  end
+
+  # --- prepare --------------------------------------------------------------
+
+  desc "Stage a release (bump + changelog) for review. Version optional; git-cliff computes it."
+  task :prepare, [:version] do |_t, args|
+    version = args[:version] || computed_next_version
+
+    unless version.match?(/^\d+\.\d+\.\d+$/)
+      abort "Error: version must be in format X.Y.Z (got #{version.inspect})"
+    end
+
+    unless `git status --porcelain`.strip.empty?
+      abort "Error: working tree is dirty. Commit or stash first."
+    end
+
+    puts "Preparing release v#{version}..."
+
+    # Bump version.rb
+    content = File.read(RELEASE_VERSION_FILE)
+    File.write(RELEASE_VERSION_FILE, content.gsub(/VERSION = "[\d.]+"/, %(VERSION = "#{version}")))
+    puts "✓ #{RELEASE_VERSION_FILE}"
+
+    # Bump the supported-version series in SECURITY.md (e.g. `0.8.x`), so the
+    # policy always names the current release series. Skipped if the file or the
+    # expected `X.Y.x` marker is missing — a release must never fail over this.
+    if File.exist?(RELEASE_SECURITY_FILE)
+      series = "#{version.split(".").first(2).join(".")}.x"
+      security = File.read(RELEASE_SECURITY_FILE)
+      updated = security.gsub(/`\d+\.\d+\.x`/, "`#{series}`")
+      if updated == security
+        puts "• #{RELEASE_SECURITY_FILE} — no `X.Y.x` marker found, skipping"
+      else
+        File.write(RELEASE_SECURITY_FILE, updated)
+        puts "✓ #{RELEASE_SECURITY_FILE}"
+      end
+    end
+
+    # Changelog — same config CI uses for release notes, so they agree.
+    abort "git-cliff not found. Install with: brew install git-cliff" unless git_cliff?
+    system("git-cliff", "--config", RELEASE_CLIFF_CONFIG, "--tag", "v#{version}", "-o", "CHANGELOG.md") ||
+      abort("Changelog generation failed")
+    puts "✓ CHANGELOG.md"
+
+    # Stage everything and show it — review happens BEFORE anything is committed.
+    system("git", "add", "-A") || abort("git add failed")
+
+    puts "\n✓ Staged release v#{version} (nothing committed yet)."
+    puts "\nStaged changes:"
+    system("git", "--no-pager", "diff", "--cached", "--stat")
+    puts "\nNext:"
+    puts "  git diff --cached     # review the full diff"
+    puts "  rake release:publish  # commit, publish gem, tag + push"
+    puts "  git reset --hard      # abort and discard the staged changes"
+  end
+
+  # --- publish (primary; idempotent + resumable) ----------------------------
+
+  desc "Commit the prepared release, publish the gem, then tag + push (fires the Release workflow)"
+  task :publish do
+    version = current_version
+    tag = "v#{version}"
+
+    # Commit the changes prepare left staged for review. If the tree is already
+    # clean (e.g. re-running after a partial failure), there's nothing to commit.
+    if `git status --porcelain`.strip.empty?
+      puts "• working tree clean — nothing to commit"
+    else
+      system("git", "add", "-A") || abort("git add failed")
+      system("git", "commit", "-m", "chore(release): prepare for v#{version}") || abort("git commit failed")
+      puts "✓ Committed release v#{version}"
+    end
+
+    # Gem (skip if this version is already on RubyGems)
+    if gem_published?(version)
+      puts "• gem #{RELEASE_GEM_NAME} #{version} already on RubyGems — skipping"
+    else
+      puts "Building + pushing gem..."
+      system("gem build #{RELEASE_GEM_NAME}.gemspec") || abort("Gem build failed")
+      gem_file = "#{RELEASE_GEM_NAME}-#{version}.gem"
+      system("gem push #{gem_file}") || abort("Gem push failed")
+      File.delete(gem_file) if File.exist?(gem_file)
+      puts "✓ Published #{RELEASE_GEM_NAME} #{version} to RubyGems"
+    end
+
+    # Tag + push last, so CI cuts the Release only once the gem is live.
+    branch = `git branch --show-current`.strip
+    if system("git rev-parse #{tag} >/dev/null 2>&1")
+      puts "• tag #{tag} already exists — skipping tag"
+    else
+      system("git", "tag", tag) || abort("git tag failed")
+    end
+    system("git", "push", "origin", branch) || abort("git push branch failed")
+    system("git", "push", "origin", tag) || abort("git push tag failed")
+
+    puts "\n✓ Released #{tag}. GitHub Actions will cut the Release from the tag."
+    puts "  Watch: https://github.com/radioactive-labs/flow_chat/actions"
+  end
+end
+
+# Neutralize the dangerous bare `rake release` that bundler/gem_tasks defines
+# (it would tag + gem push directly). Point people at the real flow instead.
+if Rake::Task.task_defined?("release")
+  Rake::Task["release"].clear
+  task :release do
+    warn "Use `rake release:prepare` then `rake release:publish`. See lib/tasks/release.rake."
+  end
+end