gsc-cli 2.0.2 → 2.2.0

data/lib/gsc/cli/sitemap_tree.rb

@@ -0,0 +1,143 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+require_relative '../sitemap_tree'
+require_relative '../color'
+
+module GSC
+  class CLI
+    module SitemapTree
+      module_function
+
+      def run(command, target, extra, options, api = nil, site_url = nil, hostname = nil)
+        target_sitemap = target || options[:sitemap]
+
+        # Auto-detection if target is not specified
+        if target_sitemap.nil? || target_sitemap.empty?
+          local_candidates = [
+            'public/sitemap.xml',
+            'public/sitemap_index.xml',
+            'dist/sitemap.xml',
+            'sitemap.xml',
+            'sitemap_index.xml'
+          ]
+          found_local = local_candidates.find { |f| File.exist?(f) }
+          if found_local
+            target_sitemap = found_local
+          elsif site_url || hostname
+            origin = site_url ? site_url.sub(/^sc-domain:/, 'https://').chomp('/') : "https://#{hostname}"
+            target_sitemap = "#{origin}/sitemap.xml"
+          elsif Config.default_domain
+            target_sitemap = "https://#{Config.default_domain}/sitemap.xml"
+          else
+            if options[:json]
+              puts JSON.pretty_generate({ error: 'Target sitemap XML URL or file required. Example: gsc sitemap-tree https://mysite.com/sitemap.xml' })
+            else
+              puts Color.c("❌ Error: Target sitemap XML URL or file required.", Color::RED, Color::BOLD)
+              puts "Example: gsc sitemap-tree https://mysite.com/sitemap.xml"
+              puts "         gsc sitemap-tree ./sitemap.xml"
+            end
+            return
+          end
+        end
+
+        gsc_pages = []
+        if api && site_url
+          gsc_res = api.query_analytics(site_url, days: options[:days] || 28, dimensions: ['page'], row_limit: 250) rescue { ok: false }
+          if gsc_res[:ok]
+            gsc_pages = (gsc_res.dig(:data, 'rows') || []).map { |r| { url: r['keys'][0], clicks: r['clicks'], imp: r['impressions'] } }
+          end
+        end
+
+        auditor = GSC::SitemapTree.new(target_sitemap, options)
+        report = auditor.audit(gsc_pages)
+
+        if options[:json]
+          puts JSON.pretty_generate(report)
+          return
+        end
+
+        render_sitemap_tree(report, options)
+
+        if options[:csv]
+          csv_rows = report[:all_urls].map do |u|
+            [u, report[:root]]
+          end
+          Base.write_csv(options[:csv], %w[URL SitemapSource], csv_rows)
+          puts Color.cyan("📁 Exported #{report[:all_urls].size} sitemap URLs to #{options[:csv]}")
+        end
+      end
+
+      def render_sitemap_tree(report, options)
+        puts "\n" + Color.cyan("╔" + "═" * 78 + "╗")
+        puts Color.cyan("║") + Color.bold("   🗺️  SITEMAP INDEX HIERARCHY & SPECIFICATION COMPLIANCE AUDITOR              ") + Color.cyan("║")
+        puts Color.cyan("╚" + "═" * 78 + "╝")
+        puts Color.gray("  Root Sitemap:     ") + Color.bold(report[:root].to_s)
+        puts Color.gray("  Structure:        ") + (report[:is_index] ? Color.cyan("Sitemap Index (Multi-file hierarchy)") : Color.dim("Single Urlset"))
+        puts Color.gray("  Total Sitemaps:   ") + Color.bold(report[:total_sitemaps].to_s)
+        puts Color.gray("  Total URLs:       ") + Color.bold(report[:total_urls].to_s)
+
+        # Health Score
+        score_color = report[:health_score] >= 85 ? Color::GREEN : (report[:health_score] >= 60 ? Color::YELLOW : Color::RED)
+        puts Color.gray("  Compliance Score: ") + Color.c("#{report[:health_score]}/100", score_color, Color::BOLD)
+        puts Color.cyan("─" * 80)
+
+        # Violations
+        if report[:violations].any?
+          puts "\n" + Color.bold("🚨 SITEMAP PROTOCOL VIOLATIONS:")
+          report[:violations].each do |v|
+            puts "   ✗ [#{v[:type].to_s.upcase}] #{v[:sitemap]}: #{Color.red(v[:message])}"
+          end
+        else
+          puts "\n" + Color.green("✓ Zero protocol violations! Conforms to Google 50,000 URLs & 50MB limits.")
+        end
+
+        # GSC Coverage
+        cov = report[:coverage]
+        if cov && cov[:total_gsc_pages] && cov[:total_gsc_pages] > 0
+          cov_color = cov[:coverage_pct] >= 90.0 ? Color::GREEN : Color::YELLOW
+          puts "\n" + Color.bold("📈 GOOGLE SEARCH CONSOLE SITEMAP COVERAGE:")
+          puts "   • Coverage Ratio:       " + Color.c("#{cov[:coverage_pct]}%", cov_color, Color::BOLD) + " (#{cov[:included_in_sitemap]}/#{cov[:total_gsc_pages]} ranking pages listed)"
+          if cov[:missing_from_sitemap] > 0
+            puts "   • Missing From Sitemap: " + Color.yellow("#{cov[:missing_from_sitemap]} pages") + Color.gray(" (ranking in GSC but omitted from sitemap)")
+            cov[:missing_sample].first(3).each do |m|
+              puts "      ↳ " + Color.dim(m)
+            end
+          end
+        end
+
+        # Visual ASCII Tree
+        puts "\n" + Color.bold("🌳 SITEMAP ARCHITECTURE TREE:")
+        print_tree_node(report[:tree], "", true)
+        puts Color.cyan("═" * 80) + "\n"
+      end
+
+      def print_tree_node(node, prefix, is_last)
+        branch = is_last ? "└── " : "├── "
+        icon = node[:type] == :sitemapindex ? "📁 " : "📄 "
+
+        lastmod_label = if node[:latest_lastmod]
+                          node[:is_stale] ? Color.yellow("[Stale: #{node[:latest_lastmod]}]") : Color.gray("[Updated: #{node[:latest_lastmod]}]")
+                        else
+                          Color.gray("[No lastmod]")
+                        end
+
+        count_label = Color.bold("#{node[:url_count] || 0} URLs")
+        size_kb = ((node[:size_bytes] || 0) / 1024.0).round(1)
+        size_label = Color.dim("(#{size_kb} KB)")
+
+        puts "#{prefix}#{branch}#{icon}#{Color.bold(node[:url])} #{count_label} #{size_label} #{lastmod_label}"
+
+        if node[:children] && node[:children].any?
+          new_prefix = prefix + (is_last ? "    " : "│   ")
+          node[:children].each_with_index do |child, idx|
+            child_is_last = (idx == node[:children].size - 1)
+            print_tree_node(child, new_prefix, child_is_last)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gsc/cli/skill_pack.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+require_relative '../skill_pack'
+require_relative '../color'
+
+module GSC
+  class CLI
+    module SkillPack
+      module_function
+
+      def run(command, target, extra, options, api = nil, site_url = nil, hostname = nil)
+        target_dir = target || (extra && extra.first)
+
+        puts "📦 Packaging autonomous AI Agent Skill specification for #{Color.cyan(target_dir || options[:target] || 'all agent platforms')}..." unless options[:json]
+
+        res = GSC::SkillPack.package(options, target_dir)
+
+        if options[:json]
+          puts JSON.pretty_generate(res)
+          return
+        end
+
+        render_terminal(res)
+      end
+
+      def render_terminal(res)
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+        puts "#{Color.bold("🤖 AUTONOMOUS AI AGENT SKILL PACKAGING & INTEGRATION")}"
+        puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+
+        puts "  • Skill Package Name:             #{Color.bold(res[:skill_name])} (v#{res[:version]})"
+        puts "  • Execution Recipes Packaged:     #{Color.bold(res[:recipes_count].to_s)} autonomous playbooks"
+        puts "  • Mode:                           #{res[:dry_run] ? Color.yellow("DRY RUN (Preview Only)") : Color.green("INSTALLED & ACTIVE")}"
+
+        v = res[:verification]
+        status_color = v[:status] == 'READY_FOR_AI_AGENTS' ? Color.green(v[:status]) : Color.red(v[:status])
+        puts "  • AI Agent Execution Health:      [ #{Color.bold(status_color)} ]"
+        puts "  • Target Binary Executable:       #{v[:binary_path]}"
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}\n"
+
+        if res[:installed_locations].any?
+          puts "#{Color.bold("INSTALLED AGENT SKILL LOCATIONS:")}\n"
+          res[:installed_locations].each do |loc|
+            puts "  ✅ #{Color.bold(loc[:platform])}:"
+            puts "     📄 SKILL.md:     #{Color.cyan(loc[:skill_path])}"
+            puts "     📋 recipes.json: #{Color.cyan(loc[:recipe_path])}\n"
+          end
+        end
+
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+        puts "#{Color.bold("AI AGENT USAGE TRIGGER PROMPT:")}"
+        puts "  Copy and paste into your AI agent or IDE (Cursor, Claude, Antigravity, Windsurf, Codex):"
+        puts Color.cyan("  \"Inspect our SEO health for my active domain using `gsc audit --json`")
+        puts Color.cyan("   and diagnose any striking distance keyword opportunities with `gsc kw-value --json`.\"")
+        puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}\n"
+      end
+    end
+  end
+end

data/lib/gsc/cli/soft_404.rb

@@ -0,0 +1,199 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base'
+require_relative '../soft_404_analyzer'
+require_relative '../color'
+
+module GSC
+  class CLI
+    module Soft404
+      module_function
+
+      def run(command, target, extra, options, api = nil, site_url = nil, hostname = nil)
+        target_url = target || (extra && extra.first) || hostname || Config.default_domain
+        if target_url.nil? || target_url.to_s.strip.empty?
+          if options[:json]
+            puts JSON.pretty_generate({ error: 'Target URL or domain required. Example: gsc soft-404 https://mydomain.com/page' })
+          else
+            puts Color.c("❌ Error: Target URL or domain required.", Color::RED, Color::BOLD)
+            puts "Example: gsc soft-404 https://mydomain.com/page"
+            puts "         gsc soft-404 mydomain.com"
+          end
+          return
+        end
+
+        puts "🔍 Auditing URLs for Soft-404 errors, thin content & HTTP status code mismatches..." unless options[:json]
+
+        res = GSC::Soft404Analyzer.analyze(target_url, options)
+
+        if options[:json]
+          puts JSON.pretty_generate(res)
+          return
+        end
+
+        if options[:csv]
+          export_csv(res)
+          return
+        end
+
+        render_terminal(res, options, extra)
+      end
+
+      def render_terminal(res, options, extra = [])
+        sum = res[:summary]
+
+        grade_color = case res[:grade]
+                      when 'A' then Color.green("#{res[:health_score]}/100 (Grade #{res[:grade]})")
+                      when 'B', 'C' then Color.yellow("#{res[:health_score]}/100 (Grade #{res[:grade]})")
+                      else Color.red("#{res[:health_score]}/100 (Grade #{res[:grade]})")
+                      end
+
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+        puts "#{Color.bold("🚫 SOFT-404 & BROKEN URL DIAGNOSTIC ENGINE")}"
+        puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+
+        puts "  • Soft-404 Health Score:     [ #{Color.bold(grade_color)} ]"
+        puts "  • Crawl Budget Waste:        #{Color.bold(Color.red("#{sum[:crawl_budget_waste_percent]}%"))} of crawled pages"
+        puts "  • URLs Audited:              #{Color.bold(res[:total_urls_audited].to_s)} total"
+        puts "  • Verified Healthy (200 OK): #{Color.green(sum[:healthy_count].to_s)}"
+        puts "  • Soft-404 Errors Flagged:   #{Color.bold(Color.red(sum[:soft_404_count].to_s))}"
+        puts "  • Hard 404/410 Broken:       #{Color.yellow(sum[:hard_404_count].to_s)}"
+        puts "  • Thin Content Warnings:     #{Color.cyan(sum[:thin_content_count].to_s)}"
+        if res[:detected_stack] && res[:detected_stack][:framework] != 'Universal Web'
+          puts "  • Detected Environment:      #{Color.bold(Color.cyan("#{res[:detected_stack][:framework]} (#{res[:detected_stack][:server]})"))}"
+        end
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}\n"
+
+        puts format("%-45s | %-5s | %-18s | %-6s | %-16s", "URL", "HTTP", "Classification", "Words", "Suggested Target")
+        puts "#{Color.bold("─" * 105)}"
+
+        res[:all_results].each do |item|
+          u_trunc = item[:url].length > 43 ? "#{item[:url][0..40]}..." : item[:url]
+          code_s = item[:status_code].to_s
+
+          class_badge = case item[:classification]
+                        when :healthy_200 then Color.green("HEALTHY")
+                        when :soft_404 then Color.red("🚨 SOFT-404")
+                        when :soft_404_redirect then Color.red("⚠️ REDIRECT-404")
+                        when :hard_404 then Color.yellow("HARD 404")
+                        when :thin_content_warning then Color.cyan("THIN CONTENT")
+                        else item[:classification].to_s.upcase
+                        end
+
+          puts format("%-45s | %-5s | %-27s | %-6d | %-16s",
+                      u_trunc, code_s, class_badge, item[:word_count], item[:suggested_redirect])
+        end
+
+        fix_urls = res[:all_results].select { |r| r[:is_soft_404] || r[:classification] == :hard_404 || r[:classification] == :soft_404_redirect }
+
+        if fix_urls.any? || options[:fix]
+          puts "\n#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+          puts "#{Color.bold("1-CLICK SERVER REWRITE RULES FOR 404 & REDIRECT RECOVERY:")}"
+
+          if fix_urls.empty?
+            puts "  (All audited URLs are verified healthy 200 OK. No redirect rules required.)"
+          else
+            fix_param = options[:fix].is_a?(String) ? options[:fix] : nil
+            valid_fmts = %w[
+              nginx caddy htaccess apache nextjs next vercel sveltekit svelte astro
+              webflow shopify cloudflare cloudflare-pages pages cf-workers workers worker
+              netlify _redirects github github-pages gh-pages gatsby all
+            ]
+            extra_fmt = (extra && extra.first.to_s) if valid_fmts.include?(extra&.first.to_s.downcase)
+
+            fmt = (options[:format] || fix_param || extra_fmt || 'nginx').to_s.downcase
+
+            case fmt
+            when 'caddy'
+              puts "  # Caddy (Caddyfile) 301 Redirect Rules:"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:caddy]}") }
+            when 'sveltekit', 'svelte'
+              puts "  // SvelteKit hooks.server.ts (or +page.server.ts):"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:sveltekit]}") }
+            when 'astro'
+              puts "  // Astro (astro.config.mjs) redirects map:"
+              puts "  redirects: {"
+              fix_urls.first(10).each { |s| puts Color.cyan("    #{s[:remediation_rules][:astro]}") }
+              puts "  }"
+            when 'gatsby'
+              puts "  // Gatsby (gatsby-node.js -> createPages):"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:gatsby]}") }
+            when 'cloudflare', 'cloudflare-pages', 'pages', 'netlify', '_redirects'
+              puts "  # Cloudflare Pages / Netlify _redirects file:"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:cloudflare]}") }
+            when 'cloudflare-workers', 'workers', 'worker', 'cf-workers'
+              puts "  // Cloudflare Workers (worker.js / ts):"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:cloudflare_workers]}") }
+            when 'github', 'github-pages', 'gh-pages'
+              puts "  <!-- GitHub Pages / Static HTML Redirect: -->"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:github_pages]}") }
+            when 'webflow'
+              puts "  # Webflow 301 Redirects (Project Settings -> Publishing -> 301 Redirects):"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:webflow]}") }
+            when 'shopify'
+              puts "  # Shopify URL Redirects (Import CSV via Online Store -> Navigation):"
+              puts "  Redirect from,Redirect to"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:shopify]}") }
+            when 'nextjs', 'next'
+              puts "  // Next.js (next.config.js) redirects array:"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:nextjs]}") }
+            when 'vercel'
+              puts "  // vercel.json redirects array:"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{JSON.generate(s[:remediation_rules][:vercel])},") }
+            when 'htaccess', 'apache', 'wordpress'
+              puts "  # Apache / WordPress .htaccess 301 Redirect Rules:"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:htaccess]}") }
+            when 'all'
+              puts "  # --- Nginx ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:nginx]}") }
+              puts "\n  # --- Caddy ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:caddy]}") }
+              puts "\n  # --- Cloudflare Pages / Netlify (_redirects) ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:cloudflare]}") }
+              puts "\n  // --- Cloudflare Workers ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:cloudflare_workers]}") }
+              puts "\n  // --- SvelteKit (hooks.server.ts) ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:sveltekit]}") }
+              puts "\n  // --- Next.js (next.config.js) ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:nextjs]}") }
+              puts "\n  // --- Astro (astro.config.mjs) ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("    #{s[:remediation_rules][:astro]}") }
+              puts "\n  // --- Gatsby (gatsby-node.js) ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:gatsby]}") }
+              puts "\n  <!-- --- GitHub Pages HTML Redirect --- -->"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:github_pages]}") }
+              puts "\n  # --- Webflow (Site Settings 301) ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:webflow]}") }
+              puts "\n  # --- Shopify CSV ---"
+              fix_urls.first(2).each { |s| puts Color.cyan("  #{s[:remediation_rules][:shopify]}") }
+            else
+              puts "  # Nginx 301 Permanent Redirect Rules:"
+              fix_urls.first(10).each { |s| puts Color.cyan("  #{s[:remediation_rules][:nginx]}") }
+            end
+
+            puts "\n💡 #{Color.gray("Tip: Generate for any stack: --fix caddy | --fix sveltekit | --fix astro | --fix cloudflare | --fix workers | --fix github | --fix gatsby | --fix webflow | --fix shopify | --fix nextjs | --fix all")}"
+          end
+        end
+
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}\n"
+      end
+
+      def export_csv(res)
+        require 'csv'
+        puts "url,status_code,classification,word_count,suggested_redirect,suggested_action"
+        res[:all_results].each do |item|
+          puts [
+            item[:url],
+            item[:status_code],
+            item[:classification],
+            item[:word_count],
+            item[:suggested_redirect],
+            item[:suggested_action]
+          ].to_csv
+        end
+      end
+    end
+  end
+end

data/lib/gsc/cli/sparkline.rb

@@ -0,0 +1,227 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'json'
+require 'date'
+require_relative 'base'
+require_relative '../sparkline'
+require_relative '../color'
+
+module GSC
+  class CLI
+    module Sparkline
+      module_function
+
+      def run(command, target, extra, options, api = nil, site_url = nil, hostname = nil)
+        days = (options[:days] || 28).to_i
+        metric_filter = (options[:metric] || 'all').to_s.downcase
+
+        # 1. Mode A: Raw numbers passed via --data or comma-separated target
+        if options[:data] || (target && target.match?(/^\d+(?:,\s*\d+)+$/))
+          raw_data = (options[:data] || target).split(',').map(&:strip).map(&:to_f)
+          render_raw_data(raw_data, options)
+          return
+        end
+
+        # 2. Mode B: Live Search Console query over time
+        filter_query = nil
+        filter_page = nil
+
+        if target && target.start_with?('/')
+          filter_page = target
+        elsif target && target.match?(%r{^https?://})
+          filter_page = target
+        elsif target && !target.empty?
+          filter_query = target
+        end
+
+        # Also check extra arguments if multi-word query was given
+        if extra && extra.is_a?(String) && !extra.empty?
+          filter_query = "#{filter_query} #{extra}".strip
+        end
+
+        daily_rows = fetch_daily_analytics(api, site_url, days, filter_query, filter_page)
+
+        if daily_rows.empty?
+          msg = "No daily time-series performance data found for #{site_url || 'current domain'} over the past #{days} days."
+          if options[:json]
+            puts JSON.pretty_generate({ error: msg })
+          else
+            puts Color.yellow("⚠️ Notice: #{msg}")
+          end
+          return
+        end
+
+        result = process_time_series(daily_rows, site_url, days, filter_query, filter_page, options)
+
+        if options[:json]
+          puts JSON.pretty_generate(result)
+          return
+        end
+
+        render_terminal(result, metric_filter, options)
+
+        if options[:csv]
+          export_csv(result, options[:csv])
+        end
+      end
+
+      def fetch_daily_analytics(api, site_url, days, query, page)
+        return [] unless api && site_url
+
+        filters = []
+        filters << { dimension: 'query', operator: 'contains', expression: query } if query
+        filters << { dimension: 'page', operator: 'contains', expression: page } if page
+
+        res = api.query_analytics(site_url, days: days, dimensions: ['date'], filters: filters, row_limit: 500)
+        if res[:ok]
+          (res.dig(:data, 'rows') || []).sort_by { |r| r['keys'].first }
+        else
+          []
+        end
+      rescue StandardError
+        []
+      end
+
+      def process_time_series(rows, site_url, days, query, page, options)
+        dates = rows.map { |r| r['keys'].first }
+        clicks = rows.map { |r| (r['clicks'] || 0).to_i }
+        impressions = rows.map { |r| (r['impressions'] || 0).to_i }
+        positions = rows.map { |r| (r['position'] || 0.0).round(1) }
+        ctrs = rows.map { |r| (r['ctr'] ? r['ctr'] * 100.0 : 0.0).round(2) }
+
+        height = [options[:height] || 5, 2].max
+
+        metrics = {
+          clicks: {
+            label: 'Clicks',
+            values: clicks,
+            total: clicks.sum,
+            average: (clicks.sum.to_f / [clicks.size, 1].max).round(1),
+            sparkline: GSC::Sparkline.render(clicks, colored: true),
+            chart: GSC::Sparkline.chart(clicks, height: height, dates: dates),
+            momentum: GSC::Sparkline.momentum(clicks)
+          },
+          impressions: {
+            label: 'Impressions',
+            values: impressions,
+            total: impressions.sum,
+            average: (impressions.sum.to_f / [impressions.size, 1].max).round(1),
+            sparkline: GSC::Sparkline.render(impressions, colored: true),
+            chart: GSC::Sparkline.chart(impressions, height: height, dates: dates),
+            momentum: GSC::Sparkline.momentum(impressions)
+          },
+          position: {
+            label: 'Avg Position',
+            values: positions,
+            average: (positions.sum.to_f / [positions.size, 1].max).round(1),
+            sparkline: GSC::Sparkline.render(positions, invert: true, colored: true),
+            chart: GSC::Sparkline.chart(positions, height: height, dates: dates),
+            momentum: GSC::Sparkline.momentum(positions)
+          },
+          ctr: {
+            label: 'CTR (%)',
+            values: ctrs,
+            average: (ctrs.sum.to_f / [ctrs.size, 1].max).round(2),
+            sparkline: GSC::Sparkline.render(ctrs, colored: true),
+            chart: GSC::Sparkline.chart(ctrs, height: height, dates: dates),
+            momentum: GSC::Sparkline.momentum(ctrs)
+          }
+        }
+
+        {
+          site_url: site_url,
+          days: days,
+          filter_query: query,
+          filter_page: page,
+          data_points: rows.size,
+          start_date: dates.first,
+          end_date: dates.last,
+          dates: dates,
+          metrics: metrics
+        }
+      end
+
+      def render_terminal(res, metric_filter, options)
+        target_desc = if res[:filter_query]
+                        "Query: \"#{res[:filter_query]}\""
+                      elsif res[:filter_page]
+                        "Page: #{res[:filter_page]}"
+                      else
+                        "Site-wide Performance"
+                      end
+
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+        puts "#{Color.bold("📈 VISUAL TREND SPARKLINES & TRAJECTORY CHARTS (#{res[:days]} Days)")}"
+        puts "#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}"
+        puts "  • Target Scope:   #{Color.cyan(target_desc)}"
+        puts "  • Time Window:    #{res[:start_date]} to #{res[:end_date]} (#{res[:data_points]} daily points)"
+        puts "#{Color.bold("───────────────────────────────────────────────────────────────────────────")}\n"
+
+        # 1. Primary ASCII Visual Chart (Clicks or chosen metric)
+        primary_key = metric_filter == 'all' ? :clicks : metric_filter.to_sym
+        primary_m = res[:metrics][primary_key] || res[:metrics][:clicks]
+
+        puts "#{Color.bold("DAILY #{primary_m[:label].upcase} TRAJECTORY (ASCII TERMINAL CHART):")}\n"
+        puts primary_m[:chart]
+        puts "\n#{Color.bold("───────────────────────────────────────────────────────────────────────────")}"
+
+        # 2. Comparative Metrics Table with Sparklines & Velocity
+        puts "#{Color.bold("30-DAY METRIC SUMMARY & MOMENTUM VECTOR:")}\n\n"
+        printf " %-14s %-20s %-12s %-10s %s\n", "Metric", "Sparkline (28d)", "Avg / Day", "Total", "Momentum Rate"
+        puts " ---------------------------------------------------------------------------------------"
+
+        res[:metrics].each do |key, m|
+          next if metric_filter != 'all' && metric_filter != key.to_s
+
+          total_display = m[:total] ? m[:total].to_s : "—"
+          avg_display = key == :ctr ? "#{m[:average]}%" : (key == :position ? "Pos #{m[:average]}" : m[:average].to_s)
+          mom_str = m[:momentum][:velocity]
+
+          printf " %-14s [ %s ] %-12s %-10s %s\n", m[:label], m[:sparkline], avg_display, total_display, mom_str
+        end
+
+        puts "\n#{Color.bold("═══════════════════════════════════════════════════════════════════════════")}\n"
+      end
+
+      def render_raw_data(data, options)
+        spark = GSC::Sparkline.render(data, colored: true)
+        chart = GSC::Sparkline.chart(data, height: options[:height] || 5)
+        mom = GSC::Sparkline.momentum(data)
+
+        if options[:json]
+          puts JSON.pretty_generate({
+            points: data.size,
+            values: data,
+            min: data.min,
+            max: data.max,
+            average: (data.sum / data.size.to_f).round(2),
+            sparkline: spark,
+            momentum: mom
+          })
+          return
+        end
+
+        puts "\n#{Color.bold("ASCII DATA CHART (#{data.size} points):")}\n"
+        puts chart
+        puts "\nSparkline: [ #{spark} ] | Momentum: #{mom[:velocity]}\n"
+      end
+
+      def export_csv(res, file_path)
+        dates = res[:dates]
+        clicks = res[:metrics][:clicks][:values]
+        impressions = res[:metrics][:impressions][:values]
+        positions = res[:metrics][:position][:values]
+        ctrs = res[:metrics][:ctr][:values]
+
+        headers = %w[Date Clicks Impressions Position CTR]
+        rows = dates.each_with_index.map do |d, i|
+          [d, clicks[i] || 0, impressions[i] || 0, positions[i] || 0.0, ctrs[i] || 0.0]
+        end
+
+        Base.write_csv(file_path, headers, rows)
+        puts Color.cyan("📁 Successfully exported daily sparkline points to #{file_path}")
+      end
+    end
+  end
+end