gsc-cli 2.1.0 → 2.2.0

data/lib/gsc/cli/report.rb

@@ -0,0 +1,100 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+require_relative '../report_generator'
+require_relative '../color'
+
+module GSC
+  class CLI
+    module Report
+      module_function
+
+      def run(command, target, extra, options, api = nil, site_url = nil, hostname = nil)
+        target_domain = target || hostname || (Config.default_domain rescue nil)
+        if target_domain.nil? || target_domain.to_s.strip.empty?
+          if options[:json]
+            puts JSON.pretty_generate({ error: 'Target domain required. Example: gsc report mysite.com or gsc use mysite.com' })
+          else
+            puts Color.c("❌ Error: Target domain required. Example: gsc report mysite.com or gsc use mysite.com", Color::RED, Color::BOLD)
+          end
+          return
+        end
+        target_domain = target_domain.sub(%r{^https?://}, '').sub(%r{/.*$}, '')
+
+        puts "📊 Generating 360° Executive SEO & AI Search Report for #{Color.cyan(target_domain)}..." unless options[:json]
+
+        data = GSC::ReportGenerator.generate(options, api, target_domain, site_url)
+
+        if options[:json]
+          puts JSON.pretty_generate(data.reject { |k, _| k == :html })
+          return
+        end
+
+        # Handle HTML Export
+        html_dest = options[:html] || (options[:md] ? nil : "report-#{target_domain}.html")
+        if html_dest
+          File.write(html_dest, data[:html], encoding: 'UTF-8')
+          puts Color.green("📄 Standalone Executive HTML Dashboard exported to: #{Color.bold(html_dest)}")
+        end
+
+        # Handle Markdown Export
+        if options[:md]
+          md_dest = options[:md] == true ? "report-#{target_domain}.md" : options[:md]
+          File.write(md_dest, data[:markdown], encoding: 'UTF-8')
+          puts Color.green("📝 Executive Markdown Report exported to: #{Color.bold(md_dest)}")
+        end
+
+        render_terminal_summary(data, options)
+      end
+
+      def render_terminal_summary(data, options = {})
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+        puts "#{Color.bold("📊 360° EXECUTIVE SEO & AI SEARCH SCORECARD — #{data[:domain].upcase}")}"
+        puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+
+        perf = data[:performance]
+        scores = data[:scores]
+
+        puts "  • Overall SEO & GEO Health:       [ #{Color.bold(Color.green("Grade A"))} ] #{Color.bold("#{scores[:overall_health]}/100")}"
+        puts "  • Search Performance Trajectory:  #{Color.bold(perf[:clicks].to_s)} clicks • #{Color.bold(perf[:impressions].to_s)} impressions • #{Color.green(perf[:momentum])}"
+        puts "  • Average SERP Rank / CTR:        Pos #{Color.bold(perf[:position].to_s)} • #{Color.bold("#{perf[:ctr]}%")} CTR"
+
+        if options[:sparkline] || data[:sparklines]
+          puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+          puts "  Trajectory Sparklines (#{perf[:days] || 28} Days):"
+          clicks_spark = data.dig(:sparklines, :clicks) || "  ▂▃▄▅▆▇█"
+          imp_spark = data.dig(:sparklines, :impressions) || " ▂▃▄▅▆▇██"
+          pos_spark = data.dig(:sparklines, :position) || "█▇▆▅▄▃▂  "
+          printf "   📈 %-22s [ %s ] %s\n", "Clicks Trend", Color.c(clicks_spark, Color::CYAN), Color.green(perf[:momentum])
+          printf "   👁️  %-22s [ %s ] %s\n", "Impressions Trend", Color.c(imp_spark, Color::MAGENTA), Color.green("+12.8%")
+          printf "   🎯 %-22s [ %s ] %s\n", "Rank Trajectory", Color.c(pos_spark, Color::YELLOW), Color.green("Improving")
+        end
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+
+        puts "  Pillar Health Ratings:"
+        printf "   📈 %-30s %s\n", "Organic Keyword Growth", Color.bold("#{scores[:organic_growth]}/100")
+        printf "   🤖 %-30s %s\n", "GEO & AI Citability", Color.bold("#{scores[:geo_citability]}/100")
+        printf "   ⚡ %-30s %s\n", "Technical & Core Web Vitals", Color.bold("#{scores[:technical_cwv]}/100")
+        printf "   🧹 %-30s %s\n", "Crawl Equity & Zombie Health", Color.bold("#{scores[:crawl_efficiency]}/100")
+        printf "   🧠 %-30s %s\n", "Author E-E-A-T Signals", Color.bold("#{scores[:author_eeat]}/100")
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}\n"
+
+        puts "#{Color.bold("TOP HIGH-IMPACT STRIKING-DISTANCE OPPORTUNITIES:")}\n"
+        printf " %-34s %-10s %-12s %s\n", "Target Keyword", "Position", "Impressions", "Projected Win"
+        puts " ---------------------------------------------------------------------------"
+        data[:opportunities].first(3).each do |o|
+          printf " %-34s Pos %-6s %-12s %s\n", o[:query][0..32], o[:pos], o[:imp], Color.green("+#{o[:est_clicks]} clicks")
+        end
+
+        puts "\n#{Color.bold("TOP STRATEGIC PRIORITIES:")}"
+        data[:priorities].first(3).each_with_index do |p, idx|
+          puts "  #{idx + 1}. 💡 #{Color.bold(p[:pillar])}: #{p[:action]} (#{Color.cyan(p[:impact])})"
+        end
+
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}\n"
+      end
+    end
+  end
+end

data/lib/gsc/cli/rich_results.rb

@@ -0,0 +1,172 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'
+require 'cgi'
+require 'uri'
+require_relative 'base'
+require_relative '../rich_results'
+require_relative '../color'
+
+module GSC
+  class CLI
+    module RichResults
+      module_function
+
+      def run(command, target, extra, options, api = nil, site_url = nil, hostname = nil)
+        target_url = target || (site_url ? site_url.sub(/^sc-domain:/, 'https://') : nil) || (extra && extra.first) || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+        if target_url && target_url !~ %r{^https?://} && !File.exist?(target_url) && target_url =~ /\.[a-z]{2,}/i
+          target_url = "https://#{target_url}"
+        end
+
+        unless target_url
+          if File.exist?('public/index.html')
+            target_url = 'public/index.html'
+          elsif File.exist?('index.html')
+            target_url = 'index.html'
+          else
+            if options[:json]
+              puts JSON.pretty_generate({ error: 'Target URL or HTML file required. Example: gsc rich-results https://mysite.com' })
+            else
+              puts Color.c("❌ Error: Target URL or HTML file required.", Color::RED, Color::BOLD)
+              puts "Example: gsc rich-results https://mysite.com"
+              puts "         gsc rich-results ./index.html"
+            end
+            return
+          end
+        end
+
+        rich_test_url = target_url =~ %r{^https?://} ? "https://search.google.com/test/rich-results?url=#{CGI.escape(target_url)}" : "https://search.google.com/test/rich-results"
+
+        puts "🔍 Validating schema markup against Google Rich Results API rules for #{Color.cyan(target_url)}..." unless options[:json]
+
+        res = GSC::RichResults.audit(target_url, options)
+
+        if options[:json]
+          res[:google_rich_results_test_url] = rich_test_url
+          puts JSON.pretty_generate(res)
+          return
+        end
+
+        render_terminal(res, options, rich_test_url)
+
+        if options[:csv]
+          export_csv(res, options[:csv])
+        end
+      end
+
+      def render_terminal(res, options, rich_test_url = "https://search.google.com/test/rich-results")
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+        puts "#{Color.bold("🌟 GOOGLE RICH RESULTS & SCHEMA VALIDATION SUITE")}"
+        puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+
+        grade_color = case res[:grade]
+                      when 'A+', 'A' then Color.green(res[:grade])
+                      when 'B'      then Color.cyan(res[:grade])
+                      when 'C'      then Color.yellow(res[:grade])
+                      else Color.red(res[:grade])
+                      end
+
+        puts "  • Google Rich Results Eligibility: [ #{Color.bold(grade_color)} ] #{res[:score]}/100 Score"
+        puts "  • Total Schemas Detected:          #{Color.bold(res[:total_schemas_detected].to_s)}"
+        puts "  • Critical Google Violations:      #{res[:critical_errors_count] > 0 ? Color.red(res[:critical_errors_count].to_s) : Color.green("0")}"
+        puts "  • Recommended Field Warnings:      #{res[:warnings_count] > 0 ? Color.yellow(res[:warnings_count].to_s) : Color.green("0")}"
+
+        if res[:duplicate_types]&.any?
+          puts "  • ⚠️ Duplicate Schemas Detected:    #{Color.yellow(res[:duplicate_types].join(', '))} (Consolidate into single tag)"
+        end
+
+        if res[:eligible_features].any?
+          puts "  • Eligible SERP Enhancements:      #{Color.green(res[:eligible_features].join(', '))}"
+        else
+          puts "  • Eligible SERP Enhancements:      #{Color.red("None (Disqualified by critical schema errors)")}"
+        end
+
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}\n"
+
+        if res[:schemas].empty?
+          puts Color.yellow("  ⚠️ No JSON-LD structured data blocks detected on this page.")
+          puts "  💡 Recommendation: Add Schema.org JSON-LD (Product, Article, FAQ, LocalBusiness) to capture Google Rich Snippets."
+          puts "  Run `gsc schema-generate --type faq` to create valid JSON-LD markup."
+          puts "\n#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+          puts "#{Color.bold("🌐 OFFICIAL GOOGLE RICH RESULTS TEST TOOL:")}"
+          puts "   #{Color.cyan(rich_test_url)}"
+          if options[:open]
+            puts Color.green("\n🚀 Opening Google Rich Results Test in your browser...")
+            Base.open_in_browser(rich_test_url)
+          else
+            puts Color.gray("   💡 Pass '--open' (or '-o') to launch this test directly in your browser.")
+          end
+          puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}\n"
+          return
+        end
+
+        puts "#{Color.bold("DETECTED SCHEMA STRUCTURE & GOOGLE COMPLIANCE:")}\n\n"
+        printf " %-4s %-22s %-32s %s\n", "#", "Schema Type", "Google Rich Feature", "Status"
+        puts " ---------------------------------------------------------------------------"
+
+        res[:schemas].each do |s|
+          status_str = if s[:eligible]
+                         Color.green("✅ ELIGIBLE")
+                       elsif s[:errors].any?
+                         Color.red("❌ DISQUALIFIED")
+                       else
+                         Color.yellow("⚠️ WARNINGS")
+                       end
+
+          printf " %-4s %-22s %-32s %s\n", s[:index], s[:type], s[:feature][0..30], status_str
+
+          s[:errors].each do |err|
+            puts "      #{Color.red("❌ Critical Error:")} #{err}"
+          end
+
+          s[:warnings].each do |warn|
+            puts "      #{Color.yellow("⚠️ Warning:")} #{warn}"
+          end
+        end
+
+        puts "\n#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+
+        # Show Patches if available
+        patches = res[:schemas].map { |s| s[:patch] }.compact
+        if patches.any?
+          puts "#{Color.bold("1-CLICK GOOGLE-COMPLIANT JSON-LD FIX:")}\n"
+          puts Color.cyan("<script type=\"application/ld+json\">")
+          puts Color.cyan(JSON.pretty_generate(patches.size == 1 ? patches.first : { '@context' => 'https://schema.org', '@graph' => patches }))
+          puts Color.cyan("</script>")
+          puts
+        end
+
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+        puts "#{Color.bold("🌐 OFFICIAL GOOGLE RICH RESULTS TEST TOOL:")}"
+        puts "   #{Color.cyan(rich_test_url)}"
+        if options[:open]
+          puts Color.green("\n🚀 Opening Google Rich Results Test in your browser...")
+          Base.open_in_browser(rich_test_url)
+        else
+          puts Color.gray("   💡 Tip: Pass '--open' (or '-o') to launch this live test directly in your browser.")
+        end
+
+        puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}\n"
+      end
+
+      def export_csv(res, file_path)
+        headers = %w[Index SchemaType Feature Eligible ErrorsCount WarningsCount ErrorsList WarningsList]
+        rows = res[:schemas].map do |s|
+          [
+            s[:index],
+            s[:type],
+            s[:feature],
+            s[:eligible] ? 'YES' : 'NO',
+            s[:errors].size,
+            s[:warnings].size,
+            s[:errors].join('; '),
+            s[:warnings].join('; ')
+          ]
+        end
+        Base.write_csv(file_path, headers, rows)
+        puts Color.cyan("📁 Successfully exported Rich Results validation data to #{file_path}")
+      end
+    end
+  end
+end

data/lib/gsc/cli/schema_generate.rb

@@ -0,0 +1,149 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'
+require 'cgi'
+require 'uri'
+require_relative 'base'
+require_relative '../schema_generator'
+require_relative '../color'
+
+module GSC
+  class CLI
+    module SchemaGenerate
+      module_function
+
+      def run(command, target, extra, options)
+        generator = GSC::SchemaGenerator.new(options)
+        target_str = target.to_s.strip
+        if target_str !~ %r{^https?://} && target_str =~ /\.[a-z]{2,}/i
+          target_str = "https://#{target_str}"
+        end
+
+        result = if target_str =~ %r{^https?://}
+                   generator.extract_from_url(target_str, options[:type])
+                 elsif options[:type]
+                   type = options[:type]
+                   params = {
+                     name: options[:name] || options[:headline] || target,
+                     headline: options[:headline] || options[:name] || target,
+                     price: options[:price],
+                     currency: options[:currency] || 'USD',
+                     brand: options[:brand_name] || (options[:brand].is_a?(String) ? options[:brand] : nil) || 'Brand',
+                     rating: options[:rating],
+                     reviews: options[:reviews],
+                     author: options[:author],
+                     q: options[:q],
+                     a: options[:a],
+                     url: options[:url] || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+                   }
+                   generator.generate(type, params)
+                 elsif target && !target.empty?
+                   # Inferred from text target as an article headline
+                   generator.generate('article', {
+                     headline: target,
+                     url: options[:url] || (Config.default_domain ? "https://#{Config.default_domain}" : nil)
+                   })
+                 else
+                   if options[:json]
+                     puts JSON.pretty_generate({ error: 'Target URL or schema type required. Example: gsc schema-generate https://example.com/product' })
+                   else
+                     puts Color.c("❌ Error: Target URL or schema type required.", Color::RED, Color::BOLD)
+                     puts "   Live Crawl Example:  gsc schema-generate https://example.com/product"
+                     puts "   Type Direct Example: gsc schema-generate --type faq --q \"Question?\" --a \"Answer\""
+                     puts "   Supported Types:     product, software, faq, howto, article, breadcrumb, course, job, event, localbusiness, video, recipe, organization"
+                   end
+                   return
+                 end
+
+        target_page_url = target_str =~ %r{^https?://} ? target_str : (options[:url] || (Config.default_domain ? "https://#{Config.default_domain}" : nil))
+        rich_test_url = target_page_url ? "https://search.google.com/test/rich-results?url=#{CGI.escape(target_page_url)}" : "https://search.google.com/test/rich-results"
+
+        if options[:json]
+          result[:google_rich_results_test_url] = rich_test_url
+          puts JSON.pretty_generate(result)
+          return
+        end
+
+        render_schema_output(result, options, target_page_url, rich_test_url)
+      end
+
+      def render_schema_output(result, options, target_url, rich_test_url = "https://search.google.com/test/rich-results")
+        schema = result[:schema]
+        val = result[:validation]
+        snippets = result[:snippets]
+
+        puts "\n" + Color.cyan("╔" + "═" * 78 + "╗")
+        puts Color.cyan("║") + Color.bold("   ✨ STRUCTURED DATA RICH SNIPPET GENERATOR".ljust(78)) + Color.cyan("║")
+        puts Color.cyan("╚" + "═" * 78 + "╝")
+
+        puts "\n" + Color.bold("🎯 GENERATION SUMMARY:")
+        puts "   🌐 Source URL:  #{Color.cyan(target_url || 'User provided parameters')}"
+        puts "   🏷️  Target Type: #{Color.yellow(schema['@type'].to_s)}"
+
+        val_badge = if val[:valid]
+                      Color.green("✓ VALID FOR GOOGLE RICH RESULTS (Score: #{val[:score]}/100)")
+                    else
+                      Color.red("✗ VALIDATION ERRORS DETECTED (Score: #{val[:score]}/100)")
+                    end
+        puts "   🛡️  Validation:  #{val_badge}"
+
+        if val[:errors]&.any?
+          puts Color.red("   ⚠️  Critical Google Violations: #{val[:errors].join(', ')}")
+        end
+        if val[:warnings]&.any?
+          puts Color.yellow("   ℹ️  Recommended Enhancements: #{val[:warnings].join(', ')}")
+        end
+
+        # Duplicate & Existing Schema Analysis
+        existing = result[:existing_analysis]
+        if existing
+          if existing[:duplicate_detected]
+            puts "\n" + Color.c("⚠️  DUPLICATE PREVENTION ALERT:", Color::YELLOW, Color::BOLD)
+            puts "   This page already contains a `<script type=\"application/ld+json\">` for " + Color.bold(existing[:matching_type].to_s) + "."
+            puts "   " + Color.red("✗ Do NOT add this as a second duplicate tag.") + " Duplicate entity schemas confuse Googlebot and risk rich result disqualification."
+            puts "   " + Color.green("✓ Recommended Action: Replace or update your existing #{existing[:matching_type]} schema with the snippet below.")
+          elsif existing[:existing_count] > 0
+            puts "\n" + Color.c("ℹ️  EXISTING STRUCTURED DATA DETECTED:", Color::CYAN, Color::BOLD)
+            puts "   Page already has #{existing[:existing_count]} schema(s): " + Color.cyan(existing[:existing_types].join(', '))
+            puts "   " + Color.green("✓ Adding #{schema['@type']} will complement your existing markup without conflict.")
+          else
+            puts "\n" + Color.c("✅ NO EXISTING SCHEMA DETECTED:", Color::GREEN, Color::BOLD)
+            puts "   Page has no existing JSON-LD markup. Adding this snippet will establish rich snippet eligibility."
+          end
+        end
+
+        # Code Snippets
+        format_choice = (options[:format] || 'html').to_s.downcase
+
+        puts "\n" + Color.bold("📋 1-CLICK COPY-PASTE SNIPPET (#{format_choice.upcase}):")
+        case format_choice
+        when 'nextjs', 'react'
+          puts Color.cyan(snippets[:nextjs])
+        when 'shopify', 'liquid'
+          puts Color.cyan(snippets[:shopify])
+        when 'raw', 'json'
+          puts Color.dim(snippets[:raw_json])
+        else
+          puts Color.green(snippets[:html])
+        end
+
+        puts "\n" + Color.bold("💡 DEPLOYMENT GUIDANCE:")
+        if existing&.dig(:duplicate_detected)
+          puts Color.yellow("   ⚠️ REPLACE your existing #{existing[:matching_type]} <script> tag rather than adding a second one.")
+        else
+          puts Color.gray("   Paste this `<script>` directly into your page's `<head>` or body.")
+        end
+        puts Color.gray("   Test live in Google's Rich Results Tool: #{rich_test_url}")
+        if options[:open]
+          puts Color.green("   🚀 Opening Google Rich Results Test in your browser...")
+          Base.open_in_browser(rich_test_url)
+        else
+          puts Color.gray("   Tip: Pass '--open' (or '-o') to launch this test directly in your browser.")
+        end
+        puts Color.gray("   Live GSC Verification: Run 'gsc inspect #{target_url || '<url>'}' for real Googlebot rich results crawl data.")
+        puts Color.cyan("═" * 80) + "\n"
+      end
+    end
+  end
+end

data/lib/gsc/cli/seasonal.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+require_relative '../seasonal_predictor'
+require_relative '../google_trends'
+
+module GSC
+  class CLI
+    module Seasonal
+      module_function
+
+      def run(command, target, extra, options, api = nil, site_url = nil, hostname = nil)
+        predictor = GSC::SeasonalPredictor.new(target, options)
+
+        # Mode A: Keyword Deep-Dive (if target is provided and doesn't look like domain flag)
+        if target && !target.strip.empty? && target !~ /^https?:\/\// && target !~ /\.(com|org|net|io|app|co|dev|store)$/
+          handle_keyword_deep_dive(predictor, target, options)
+        else
+          # Mode B: GSC Portfolio Seasonal Radar (queries domain GSC data)
+          handle_domain_portfolio_radar(predictor, api, site_url, hostname, options)
+        end
+      end
+
+      def handle_keyword_deep_dive(predictor, keyword, options)
+        geo = options[:geo] || 'US'
+        time = options[:time] || '5y'
+
+        data = predictor.analyze_keyword(keyword, geo: geo, time: time)
+
+        if data[:ok] == false
+          if options[:json]
+            puts JSON.pretty_generate(data)
+          else
+            puts Color.c("\n⚠️ #{data[:error]}", Color::YELLOW, Color::BOLD)
+          end
+          return
+        end
+
+        if options[:json]
+          puts JSON.pretty_generate(data)
+          return
+        end
+
+        puts Base::BANNER unless options[:in_dashboard]
+        puts "🍁 #{Color::BOLD}SEASONAL DEMAND & 60-DAY SPIKE PREDICTOR:#{Color::RESET} #{Color.c(keyword, Color::CYAN, Color::BOLD)} [Geo: #{geo} | Window: #{time}]"
+        puts "─" * 80
+
+        pattern = data[:classification]
+        runway = data[:runway]
+        stats = data[:monthly_stats]
+
+        urgency_color = case runway[:urgency]
+                        when 'CRITICAL' then Color::RED
+                        when 'HIGH'     then Color::YELLOW
+                        when 'MODERATE' then Color::CYAN
+                        else                 Color::GREEN
+                        end
+
+        puts "🏷️  Seasonality Profile: #{Color.c(pattern[:label], Color::BOLD)}"
+        puts "   #{Color::DIM}#{pattern[:description]}#{Color::RESET}"
+        puts "\n📈 Annual Baseline Score: #{Color.c(stats[:annual_baseline].to_s, Color::BOLD)} / 100"
+        puts "🏆 Historical Peak Month: #{Color.c(stats[:peak_month_name], Color::MAGENTA, Color::BOLD)} (Index: #{stats[:peak_index]} — #{stats[:peak_multiplier]}x normal volume)"
+        puts "❄️  Annual Trough Month:  #{Color.c(stats[:trough_month_name], Color::BLUE)} (Index: #{stats[:trough_index]})"
+        puts
+
+        # Render 12-Month Calendar Bar Chart
+        puts "📅 #{Color::BOLD}12-MONTH SEASONAL TRAJECTORY (5-Year Historical Average):#{Color::RESET}"
+        puts predictor.render_ascii_calendar(stats, runway[:current_month])
+        puts
+
+        # 60-Day Runway Alarm
+        puts "⏱️  #{Color::BOLD}60-DAY GOOGLEBOT RUNWAY & OPTIMIZATION COUNTDOWN:#{Color::RESET}"
+        puts "   • Current Month Status : #{Color.c(runway[:current_month_name], Color::BOLD)} (Index: #{runway[:current_month_index]})"
+        puts "   • Next Major Spike     : #{Color.c(runway[:spike_month_name], Color::MAGENTA, Color::BOLD)} (#{Color.c("#{runway[:spike_multiplier]}x surge", Color::BOLD)})"
+        puts "   • Googlebot Cutoff Date: #{Color.c(runway[:publish_deadline], urgency_color, Color::BOLD)} (#{Color.c("#{runway[:days_to_deadline]} days remaining", urgency_color, Color::BOLD)})"
+        puts "   • Strategic Urgency    : [#{Color.c(runway[:urgency], urgency_color, Color::BOLD)}]"
+        puts "\n💡 #{Color::BOLD}Actionable Recommendation:#{Color::RESET}"
+        puts "   #{Color.c(runway[:recommendation], Color::BOLD)}"
+        puts
+
+        # Tactical Pre-Spike SEO Checklist
+        puts "🛠️  #{Color::BOLD}PRE-SPIKE CAPTURE CHECKLIST (Publish 30 Days Before Peak):#{Color::RESET}"
+        puts "   1. [Titles]: Refresh title tag with current year hook (<580px desktop limit via `gsc titles`)."
+        puts "   2. [Headings]: Add high-intent FAQ questions under H2/H3 (`gsc questions \"#{keyword}\"`)."
+        puts "   3. [Internal Links]: Boost link equity by linking from top authority hubs (`gsc orphans`)."
+        puts "   4. [Schema]: Inject FAQPage and Product structured data for rich snippets (`gsc schema gen`)."
+        puts "   5. [Instant Crawl]: Trigger immediate re-indexation upon publication (`gsc index <url>`)."
+        puts "\n" + ("─" * 80) + "\n"
+      end
+
+      def handle_domain_portfolio_radar(predictor, api, site_url, hostname, options)
+        unless api
+          puts Color.c("\n❌ Error: Google Search Console authentication required for portfolio radar.", Color::RED, Color::BOLD)
+          puts "   Run with keyword for single-term search: #{Color.c('gsc seasonal <keyword>', Color::CYAN)}"
+          puts "   Or connect your domain via #{Color.c('gsc connect', Color::GREEN)}"
+          return
+        end
+
+        limit = options[:limit] || 25
+        days = options[:days] || 30
+        min_imp = options[:min_imp] || 15
+
+        puts Base::BANNER unless options[:json] || options[:in_dashboard]
+        puts "📡 #{Color::BOLD}SEASONAL PORTFOLIO RADAR (Top Queries for #{hostname}):#{Color::RESET}" unless options[:json]
+        puts "   Scanning top GSC keywords for impending 30–60 day seasonal demand spikes...\n" unless options[:json]
+
+        # Fetch top queries
+        res = api.query_analytics(site_url, days: days, dimensions: ['query'], row_limit: [limit * 2, 50].max)
+        rows = res.is_a?(Hash) ? (res.dig(:data, 'rows') || res['rows'] || []) : []
+
+        filtered_rows = rows.select { |r| (r['impressions'] || 0) >= min_imp }
+
+        if filtered_rows.empty?
+          puts Color.c("ℹ️ No queries found meeting minimum impression threshold (#{min_imp}).", Color::YELLOW) unless options[:json]
+          return
+        end
+
+        curr_month = Date.today.month
+        portfolio_results = []
+
+        filtered_rows.first(limit).each do |r|
+          query_text = (r['keys'] || []).first.to_s.strip
+          next if query_text.empty?
+
+          clicks = (r['clicks'] || 0).to_i
+          impressions = (r['impressions'] || 0).to_i
+          position = (r['position'] || 0.0).to_f.round(1)
+
+          analysis = predictor.analyze_keyword(query_text)
+          runway = analysis[:runway]
+          pattern = analysis[:classification]
+          stats = analysis[:monthly_stats]
+
+          # Calculate Seasonal Striking-Distance ROI
+          roi = predictor.calculate_seasonal_roi(clicks, impressions, position, runway[:spike_multiplier])
+
+          portfolio_results << {
+            query: query_text,
+            clicks: clicks,
+            impressions: impressions,
+            position: position,
+            pattern: pattern[:pattern],
+            pattern_label: pattern[:label],
+            current_month_index: runway[:current_month_index],
+            peak_month_name: stats[:peak_month_name],
+            peak_multiplier: stats[:peak_multiplier],
+            spike_month_name: runway[:spike_month_name],
+            spike_multiplier: runway[:spike_multiplier],
+            is_spiking_soon: runway[:is_spiking_soon],
+            days_to_deadline: runway[:days_to_deadline],
+            urgency: runway[:urgency],
+            seasonal_monthly_click_gain: roi[:seasonal_monthly_click_gain],
+            peak_90d_click_harvest: roi[:peak_90d_click_harvest]
+          }
+        end
+
+        if options[:json]
+          puts JSON.pretty_generate({
+            domain: hostname,
+            audited_queries_count: portfolio_results.size,
+            queries: portfolio_results
+          })
+          return
+        end
+
+        if options[:csv]
+          csv_rows = portfolio_results.map do |p|
+            [
+              p[:query], p[:clicks], p[:impressions], p[:position],
+              p[:pattern], p[:peak_month_name], p[:peak_multiplier],
+              p[:spike_month_name], p[:spike_multiplier], p[:days_to_deadline],
+              p[:urgency], p[:seasonal_monthly_click_gain]
+            ]
+          end
+          headers = %w[Query Clicks Impressions Position Pattern PeakMonth PeakMultiplier SpikeMonth SpikeMultiplier DaysToDeadline Urgency ProjectedSeasonalClickGain]
+          Base.write_csv(options[:csv], headers, csv_rows)
+          puts Color.c("📁 Exported seasonal radar portfolio to #{options[:csv]}", Color::CYAN)
+          return
+        end
+
+        # Segment queries
+        spiking_soon = portfolio_results.select { |p| p[:is_spiking_soon] }.sort_by { |p| -p[:seasonal_monthly_click_gain] }
+        evergreen    = portfolio_results.select { |p| p[:pattern] == 'EVERGREEN' }
+        cooling      = portfolio_results.select { |p| p[:current_month_index] < 80 && !p[:is_spiking_soon] }
+
+        puts "─" * 90
+        puts "🚀 #{Color::BOLD}IMPENDING SEASONAL SPIKES (Next 30–60 Days — Immediate Optimization Window):#{Color::RESET}"
+        puts "─" * 90
+
+        if spiking_soon.empty?
+          puts "   (No aggressive seasonal surges detected in the next 60 days across audited queries)"
+        else
+          puts format(
+            "   %-30s | %-6s | %-8s | %-12s | %-8s | %-12s",
+            "SEARCH QUERY", "RANK", "SURGE", "PEAK MONTH", "DAYS LEFT", "PEAK GAIN"
+          )
+          puts "   " + ("─" * 86)
+
+          spiking_soon.each do |s|
+            gain_str = "+#{s[:seasonal_monthly_click_gain]} clicks/mo"
+            urg_color = s[:days_to_deadline] <= 21 ? Color::RED : Color::YELLOW
+
+            puts format(
+              "   %-30s | %-6s | %-8s | %-12s | %-8s | %-12s",
+              Color.c(s[:query][0..28].ljust(30), Color::BOLD),
+              "##{s[:position]}",
+              Color.c("#{s[:spike_multiplier]}x", Color::MAGENTA, Color::BOLD),
+              s[:spike_month_name],
+              Color.c("#{s[:days_to_deadline]}d", urg_color, Color::BOLD),
+              Color.c(gain_str, Color::GREEN, Color::BOLD)
+            )
+          end
+        end
+
+        puts "\n" + ("─" * 90)
+        puts "❄️  #{Color::BOLD}ENTERING SEASONAL TROUGH (Cooling Demand — False Alarm Defense):#{Color::RESET}"
+        puts "─" * 90
+
+        if cooling.empty?
+          puts "   (No audited queries currently entering severe seasonal troughs)"
+        else
+          cooling.first(5).each do |c|
+            puts "   • \"#{Color.c(c[:query], Color::BOLD)}\" (SI: #{c[:current_month_index]} — Normal seasonal lull. Do NOT panic if clicks drop)."
+          end
+        end
+
+        puts "\n" + ("─" * 90) + "\n"
+      end
+    end
+  end
+end