gsc-cli 2.2.3 → 2.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6cfd0972501711b114e27b2a286612efcfe85bd51aaf91947bc44b8fdfd9aff
-  data.tar.gz: 5bd6e630844f13a3115bbb4c54deda04f7f3e1585c79ac4d9037dd7c216d02a1
+  metadata.gz: b146c585e5fdbbea6d4b61644f052df6e75b418d64666d4b4b6006825f0e6eaf
+  data.tar.gz: 04b24385606b02d483f14db0759848890aba51714b2fca731b483d9d88bf3346
 SHA512:
-  metadata.gz: ab41e83aa4f41ca0d296218f288cb2291275c893cf60347d6cbc7083371430e06feebf00aa084d5c5978fd0bd0bd5a35f29a1beaf5839f322f2efc629bf38429
-  data.tar.gz: 50ea5330dee9bae3b09570be862e69c3b4ec5e1aafc7126525bdd2dbe1a894c2392204749b5c7f187d32c0273530cc55f6ba66599502068b8870f1a7bdcd3f6b
+  metadata.gz: 3e2fa01bad3d160440d6ec93be6738dfeba193e7a89e380132b1f0f4c6abd8d2f311746ebe850c5af0cd95f303e3474996d0e640bdf336e2deec50482bedac4b
+  data.tar.gz: 9bbab9f7af4f23c285c7c22e5b8012a71633832a3c899b00ccf5e3f1ac1610b11bde8702cd6b5c6868641f0d55b359fdf72dba16d55cd877f662f5ba5134464a

data/README.md

@@ -494,13 +494,19 @@ gsc use 2
 | `gsc index <url>` | — | Priority Googlebot crawl submission (`URL_UPDATED`) | `--dry-run`, `--json` |
 | `gsc remove <url>` | — | Notify Googlebot of permanently deleted URL (`URL_DELETED`) | `--dry-run`, `--json` |
 | `gsc status <url>` | — | Check Google Indexing API submission status and latest notification timestamp| `--json` |
-| `gsc index-batch` | — | Batch URL indexing processor with daily 200-URL quota tracking | `--run`, `--status`, `--json` |
+| `gsc index-batch` | — | Batch URL indexing processor with daily 200-URL quota tracking | `--batch-size`, `--force`, `--dry-run`, `--json` |
 | `gsc indexnow <url>` | — | Multi-engine instant submission (Bing, Yandex, Seznam, Naver) | `--key`, `--json` |
 | `gsc zombies <sitemap>` | — | Detect zero-impression deadweight URLs wasting crawl budget over 90 days | `--days`, `--json` |
 | `gsc sitemaps-list` | — | List registered XML sitemaps in Search Console | `--json` |
 | `gsc sitemaps-submit <url>`| — | Submit or re-submit an XML sitemap to Search Console | `--json` |
 | `gsc sitemap-tree <url>` | — | Visual sitemap hierarchy tree and URL limit validator | `--json` |
 
+> 🛡️ **Batch Indexing Safety Guard (`gsc index-batch clear`)**:  
+> When automating bulk indexing in scripts, CI/CD, or AI agents, an accidental `clear` could wipe hundreds of queued URLs waiting to be indexed. To prevent queue loss:
+> - **Interactive Shells**: Requires explicit `[y/N]` user confirmation.
+> - **Non-Interactive / Scripts / Agents**: Requires `--force` / `-f` (aborts with exit code `1` if omitted).
+> - **Automatic Backup**: Every clear automatically snapshots the pending queue to `~/.gsc/backups/queue_backup_<TIMESTAMP>.json` before wiping, so URLs are never lost.
+
 ### 6. Keyword Research & Demand Trends
 | Command | Shortcut | Description | Flags |
 |---|---|---|---|

data/bin/gsc

@@ -3,7 +3,7 @@
 
 # ==============================================================================
 # Google Search Console & Indexing API CLI Tool (Pure Ruby - Zero Gem Dependencies)
-# Standalone Single-File Distribution (Built from lib/gsc v2.2.3)
+# Standalone Single-File Distribution (Built from lib/gsc v2.2.5)
 # ==============================================================================
 
 require 'net/http'
@@ -20,7 +20,7 @@ require 'stringio'
 
 # --- version.rb ---
 module GSC
-  VERSION = '2.2.3'
+  VERSION = '2.2.5'
 end
 
 # --- color.rb ---
@@ -70,7 +70,13 @@ module GSC
     CONFIG_DIR  = File.expand_path('~/.config/gsc')
     CONFIG_FILE = File.join(CONFIG_DIR, 'config.json')
 
-def self.get(key)
+    def self.ensure_gsc_symlink!
+      gsc_dir = File.expand_path('~/.gsc')
+      return if File.exist?(gsc_dir) || File.symlink?(gsc_dir)
+      File.symlink(CONFIG_DIR, gsc_dir) rescue nil
+    end
+
+    def self.get(key)
   load[key.to_s]
 end
 
@@ -3174,6 +3180,29 @@ module GSC
 
       overall_category = data.dig('loadingExperience', 'overall_category') || data.dig('originLoadingExperience', 'overall_category')
 
+      # Official Google Core Web Vitals Assessment evaluates ONLY the 3 Core Web Vitals:
+      # LCP, INP (or legacy FID), and CLS. (FCP and TTFB are diagnostic metrics).
+      # - PASSED: All present CWV metrics are 'FAST' (Good).
+      # - POOR: Any CWV metric is 'SLOW' (Poor).
+      # - NEEDS IMPROVEMENT: No CWV metric is 'SLOW', but at least one is 'AVERAGE'.
+      cwv_keys = ['LARGEST_CONTENTFUL_PAINT_MS', 'INTERACTION_TO_NEXT_PAINT', 'CUMULATIVE_LAYOUT_SHIFT_SCORE']
+      cwv_keys[1] = 'FIRST_INPUT_DELAY_MS' if !crux_metrics.key?('INTERACTION_TO_NEXT_PAINT') && crux_metrics.key?('FIRST_INPUT_DELAY_MS')
+
+      active_cwv = cwv_keys.map { |k| crux_metrics[k] }.compact
+      cwv_assessment = if active_cwv.any?
+        if active_cwv.any? { |m| m[:category] == 'SLOW' }
+          'POOR'
+        elsif active_cwv.any? { |m| m[:category] == 'AVERAGE' }
+          'NEEDS IMPROVEMENT'
+        elsif active_cwv.all? { |m| m[:category] == 'FAST' }
+          'PASSED'
+        else
+          overall_category
+        end
+      else
+        overall_category
+      end
+
       # Opportunities
       opportunities = []
       audits.each do |k, v|
@@ -3205,6 +3234,7 @@ module GSC
         field_data: crux_metrics,
         field_source: crux_source,
         overall_category: overall_category,
+        cwv_assessment: cwv_assessment,
         opportunities: opportunities.first(5)
       }
     end
@@ -5405,13 +5435,16 @@ require 'time'
 module GSC
   class IndexingQueue
     QUEUE_FILE = File.join(Config::CONFIG_DIR, 'indexing_queue.json')
+    BACKUPS_DIR = File.join(Config::CONFIG_DIR, 'backups')
     DAILY_LIMIT = 200
 
-    attr_reader :state
+    attr_reader :state, :file_path, :backup_dir
 
-    def initialize(file_path = QUEUE_FILE)
+    def initialize(file_path = QUEUE_FILE, backup_dir: nil)
       @file_path = file_path
+      @backup_dir = backup_dir || File.join(File.dirname(@file_path), 'backups')
       @state = load_state
+      Config.ensure_gsc_symlink!
     end
 
     def add_urls(urls)
@@ -5443,7 +5476,41 @@ module GSC
       }
     end
 
-    def clear(scope = :all)
+    def backup(scope = :all)
+      pending = @state['pending'] || []
+      submitted = @state['submitted'] || []
+      failed = @state['failed'] || []
+
+      # Nothing to backup if completely empty
+      return nil if pending.empty? && submitted.empty? && failed.empty?
+
+      FileUtils.mkdir_p(@backup_dir)
+      timestamp = Time.now.utc.strftime('%Y%m%d_%H%M%S')
+      backup_file = File.join(@backup_dir, "queue_backup_#{timestamp}.json")
+      if File.exist?(backup_file)
+        backup_file = File.join(@backup_dir, "queue_backup_#{timestamp}_#{Time.now.to_f.to_s.split('.').last}.json")
+      end
+
+      snapshot = {
+        'timestamp' => Time.now.utc.iso8601,
+        'cleared_scope' => scope.to_s,
+        'count' => pending.size,
+        'pending' => pending,
+        'submitted' => submitted,
+        'failed' => failed,
+        'daily_quota_used' => @state['daily_quota_used'] || 0,
+        'last_reset_date' => @state['last_reset_date']
+      }
+
+      File.write(backup_file, JSON.pretty_generate(snapshot))
+      backup_file
+    end
+
+    def clear(scope = :all, backup: true)
+      pending = @state['pending'] || []
+      count = pending.size
+      backup_file = backup ? backup(scope) : nil
+
       if scope == :pending
         @state['pending'] = []
       else
@@ -5452,6 +5519,8 @@ module GSC
         @state['failed'] = []
       end
       save_state
+
+      { count: count, backup_file: backup_file }
     end
 
     def process_batch(api, batch_size: 50, dry_run: false, delay_sec: 0.15)
@@ -9039,7 +9108,7 @@ COMMAND_REGISTRY = [
     commands: [
       { name: "inspect <url>", shortcut: nil, desc: "Live Google index check (coverage, canonical, date, robots.txt)", flags: ["-d"] },
       { name: "index <url>", shortcut: nil, desc: "Notify Googlebot to crawl/index URL immediately (URL_UPDATED)", flags: ["--dry-run"] },
-      { name: "index-batch [action]", shortcut: "ib", desc: "Automated 200 URL/day quota queue manager (add, run, status, clear)", flags: ["--batch-size", "--dry-run", "--json"] },
+      { name: "index-batch [action]", shortcut: "ib", desc: "Automated 200 URL/day quota queue manager (add, run, status, clear)", flags: ["--batch-size", "--dry-run", "--force", "--json"] },
       { name: "remove <url>", shortcut: nil, desc: "Notify Googlebot a page has been deleted (URL_DELETED)", flags: ["--dry-run"] },
       { name: "status <url>", shortcut: nil, desc: "Check Google Indexing API notification metadata", flags: [] },
       { name: "sitemaps-list", shortcut: nil, desc: "List registered XML sitemaps in Search Console", flags: ["-d"] },
@@ -21010,11 +21079,54 @@ module GSC
           end
 
         when 'clear', 'reset'
-          queue.clear(:all)
+          count = (queue.state['pending'] || []).size
+          if count == 0
+            if options[:json]
+              puts JSON.pretty_generate({ ok: true, message: 'Batch queue is already empty.', count: 0 })
+            else
+              puts "Batch queue is already empty."
+            end
+            return
+          end
+
+          unless options[:force]
+            if $stdin.tty?
+              $stdout.print "Are you sure you want to clear #{count} pending URLs from the batch queue? [y/N]: "
+              $stdout.flush
+              ans = $stdin.gets.to_s.strip.downcase
+              unless ans == 'y' || ans == 'yes'
+                if options[:json]
+                  puts JSON.pretty_generate({ ok: false, message: 'Clear aborted. Queue preserved.' })
+                else
+                  puts "Clear aborted. Queue preserved."
+                end
+                return
+              end
+            else
+              error_msg = "Error: 'gsc index-batch clear' requires '--force' in non-interactive environments to prevent accidental queue loss."
+              if options[:json]
+                puts JSON.pretty_generate({ error: error_msg })
+              else
+                puts error_msg
+              end
+              exit 1
+            end
+          end
+
+          res = queue.clear(:all, backup: true)
+          backup_path = res[:backup_file]
+          display_backup = backup_path ? backup_path.sub(/^#{Regexp.escape(Dir.home)}\/\.config\/gsc/, '~/.gsc').sub(/^#{Regexp.escape(Dir.home)}/, '~') : 'none'
+          cleared_count = res[:count] || count
+
           if options[:json]
-            puts JSON.pretty_generate({ ok: true, message: 'Queue cleared' })
+            puts JSON.pretty_generate({
+              ok: true,
+              message: "Queue cleared (#{cleared_count} items). Backup saved to #{display_backup}",
+              cleared_count: cleared_count,
+              backup_file: backup_path
+            })
           else
-            puts Color.c("🗑️  Indexing queue cleared.", Color::GREEN)
+            puts "Queue cleared (#{cleared_count} items). Backup saved to #{display_backup}"
           end
 
         else
@@ -21032,7 +21144,13 @@ module GSC
             puts "\nCommands:"
             puts "   • #{Color.c('gsc index-batch add <url|sitemap.xml|file.txt>', Color::CYAN)} - Enqueue URLs"
             puts "   • #{Color.c('gsc index-batch run [--batch-size 50] [--dry-run]', Color::CYAN)} - Process queue"
-            puts "   • #{Color.c('gsc index-batch clear', Color::CYAN)}                           - Reset queue"
+            puts "   • #{Color.c('gsc index-batch clear [--force]', Color::CYAN)}                   - Reset queue (safe wipe)"
+            puts ""
+            puts "🛡️  #{Color::BOLD}Queue Safety Guard:#{Color::RESET}"
+            puts "   • Prevents accidental queue loss from scripts, cron, or AI agents"
+            puts "   • Interactive: Prompts for confirmation [y/N] before clearing"
+            puts "   • Non-interactive / CI: Requires #{Color.c('--force', Color::YELLOW)} flag to proceed"
+            puts "   • Snapshot backup: Automatically saves a backup to ~/.gsc/backups/ before clearing"
             puts ""
           end
         end
@@ -22857,10 +22975,19 @@ module GSC
         fd = data[:field_data] || {}
         if fd.any?
           source_label = data[:field_source] == :origin ? "Domain-Wide Origin RUM" : "URL-Level RUM"
-          overall = data[:overall_category] || "UNKNOWN"
-          overall_col = overall == 'FAST' ? Color::GREEN : (overall == 'AVERAGE' ? Color::YELLOW : Color::RED)
+          assessment = data[:cwv_assessment] || data[:overall_category] || "UNKNOWN"
+          assessment_badge = case assessment
+          when 'PASSED', 'FAST'
+            Color.c("PASSED (All 3 Metrics Good)", Color::GREEN, Color::BOLD)
+          when 'NEEDS IMPROVEMENT', 'AVERAGE'
+            Color.c("NEEDS IMPROVEMENT", Color::YELLOW, Color::BOLD)
+          when 'POOR', 'SLOW', 'FAILED'
+            Color.c("FAILED (Poor Metrics Detected)", Color::RED, Color::BOLD)
+          else
+            Color.c(assessment, Color::YELLOW, Color::BOLD)
+          end
           puts "\n#{Color::BOLD}🌐 CrUX FIELD DATA (28-Day Real User Monitoring - #{source_label}):#{Color::RESET}"
-          puts "   • Core Web Vitals Status        : #{Color.c(overall, overall_col, Color::BOLD)}"
+          puts "   • Core Web Vitals Assessment    : #{assessment_badge}"
 
           if fd['LARGEST_CONTENTFUL_PAINT_MS']
             val = "#{(fd['LARGEST_CONTENTFUL_PAINT_MS'][:percentile].to_f / 1000).round(2)} s"
@@ -30016,10 +30143,19 @@ module GSC
       fd = data[:field_data] || {}
       if fd.any?
         source_label = data[:field_source] == :origin ? "Domain-Wide Origin RUM" : "URL-Level RUM"
-        overall = data[:overall_category] || "UNKNOWN"
-        overall_col = overall == 'FAST' ? Color::GREEN : (overall == 'AVERAGE' ? Color::YELLOW : Color::RED)
+        assessment = data[:cwv_assessment] || data[:overall_category] || "UNKNOWN"
+        assessment_badge = case assessment
+        when 'PASSED', 'FAST'
+          Color.c("PASSED (All 3 Metrics Good)", Color::GREEN, Color::BOLD)
+        when 'NEEDS IMPROVEMENT', 'AVERAGE'
+          Color.c("NEEDS IMPROVEMENT", Color::YELLOW, Color::BOLD)
+        when 'POOR', 'SLOW', 'FAILED'
+          Color.c("FAILED (Poor Metrics Detected)", Color::RED, Color::BOLD)
+        else
+          Color.c(assessment, Color::YELLOW, Color::BOLD)
+        end
         puts "\n#{Color::BOLD}🌐 CrUX FIELD DATA (28-Day Real User Monitoring - #{source_label}):#{Color::RESET}"
-        puts "   • Core Web Vitals Status        : #{Color.c(overall, overall_col, Color::BOLD)}"
+        puts "   • Core Web Vitals Assessment    : #{assessment_badge}"
 
         if fd['LARGEST_CONTENTFUL_PAINT_MS']
           val = "#{(fd['LARGEST_CONTENTFUL_PAINT_MS'][:percentile].to_f / 1000).round(2)} s"
@@ -31529,6 +31665,10 @@ module GSC
           options[:batch_size] = size
         end
 
+        opts.on('-f', '--force', '--yes', '-y', 'Bypass confirmation prompts (required for non-interactive queue clears)') do
+          options[:force] = true
+        end
+
         opts.on('--concurrency COUNT', Integer, 'Concurrent threads for multi-page site crawler (default: 5, max: 20)') do |c|
           options[:concurrency] = c
         end
@@ -32185,6 +32325,14 @@ module GSC
         Audit.run(command, target, extra, options)
         exit 0 unless options[:in_dashboard]
         return
+
+      when 'index-batch', 'queue', 'batch-index'
+        action = target.to_s.strip.downcase
+        if action != 'run' && action != 'process' && action != 'execute'
+          Indexing.run(command, target, extra, options, nil, nil, nil, nil)
+          exit 0 unless options[:in_dashboard]
+          return
+        end
       end
 
       # 7. Authenticated Commands (GSC / Indexing / Analytics / GA4)

data/dist/gsc

@@ -3,7 +3,7 @@
 
 # ==============================================================================
 # Google Search Console & Indexing API CLI Tool (Pure Ruby - Zero Gem Dependencies)
-# Standalone Single-File Distribution (Built from lib/gsc v2.2.3)
+# Standalone Single-File Distribution (Built from lib/gsc v2.2.5)
 # ==============================================================================
 
 require 'net/http'
@@ -20,7 +20,7 @@ require 'stringio'
 
 # --- version.rb ---
 module GSC
-  VERSION = '2.2.3'
+  VERSION = '2.2.5'
 end
 
 # --- color.rb ---
@@ -70,7 +70,13 @@ module GSC
     CONFIG_DIR  = File.expand_path('~/.config/gsc')
     CONFIG_FILE = File.join(CONFIG_DIR, 'config.json')
 
-def self.get(key)
+    def self.ensure_gsc_symlink!
+      gsc_dir = File.expand_path('~/.gsc')
+      return if File.exist?(gsc_dir) || File.symlink?(gsc_dir)
+      File.symlink(CONFIG_DIR, gsc_dir) rescue nil
+    end
+
+    def self.get(key)
   load[key.to_s]
 end
 
@@ -3174,6 +3180,29 @@ module GSC
 
       overall_category = data.dig('loadingExperience', 'overall_category') || data.dig('originLoadingExperience', 'overall_category')
 
+      # Official Google Core Web Vitals Assessment evaluates ONLY the 3 Core Web Vitals:
+      # LCP, INP (or legacy FID), and CLS. (FCP and TTFB are diagnostic metrics).
+      # - PASSED: All present CWV metrics are 'FAST' (Good).
+      # - POOR: Any CWV metric is 'SLOW' (Poor).
+      # - NEEDS IMPROVEMENT: No CWV metric is 'SLOW', but at least one is 'AVERAGE'.
+      cwv_keys = ['LARGEST_CONTENTFUL_PAINT_MS', 'INTERACTION_TO_NEXT_PAINT', 'CUMULATIVE_LAYOUT_SHIFT_SCORE']
+      cwv_keys[1] = 'FIRST_INPUT_DELAY_MS' if !crux_metrics.key?('INTERACTION_TO_NEXT_PAINT') && crux_metrics.key?('FIRST_INPUT_DELAY_MS')
+
+      active_cwv = cwv_keys.map { |k| crux_metrics[k] }.compact
+      cwv_assessment = if active_cwv.any?
+        if active_cwv.any? { |m| m[:category] == 'SLOW' }
+          'POOR'
+        elsif active_cwv.any? { |m| m[:category] == 'AVERAGE' }
+          'NEEDS IMPROVEMENT'
+        elsif active_cwv.all? { |m| m[:category] == 'FAST' }
+          'PASSED'
+        else
+          overall_category
+        end
+      else
+        overall_category
+      end
+
       # Opportunities
       opportunities = []
       audits.each do |k, v|
@@ -3205,6 +3234,7 @@ module GSC
         field_data: crux_metrics,
         field_source: crux_source,
         overall_category: overall_category,
+        cwv_assessment: cwv_assessment,
         opportunities: opportunities.first(5)
       }
     end
@@ -5405,13 +5435,16 @@ require 'time'
 module GSC
   class IndexingQueue
     QUEUE_FILE = File.join(Config::CONFIG_DIR, 'indexing_queue.json')
+    BACKUPS_DIR = File.join(Config::CONFIG_DIR, 'backups')
     DAILY_LIMIT = 200
 
-    attr_reader :state
+    attr_reader :state, :file_path, :backup_dir
 
-    def initialize(file_path = QUEUE_FILE)
+    def initialize(file_path = QUEUE_FILE, backup_dir: nil)
       @file_path = file_path
+      @backup_dir = backup_dir || File.join(File.dirname(@file_path), 'backups')
       @state = load_state
+      Config.ensure_gsc_symlink!
     end
 
     def add_urls(urls)
@@ -5443,7 +5476,41 @@ module GSC
       }
     end
 
-    def clear(scope = :all)
+    def backup(scope = :all)
+      pending = @state['pending'] || []
+      submitted = @state['submitted'] || []
+      failed = @state['failed'] || []
+
+      # Nothing to backup if completely empty
+      return nil if pending.empty? && submitted.empty? && failed.empty?
+
+      FileUtils.mkdir_p(@backup_dir)
+      timestamp = Time.now.utc.strftime('%Y%m%d_%H%M%S')
+      backup_file = File.join(@backup_dir, "queue_backup_#{timestamp}.json")
+      if File.exist?(backup_file)
+        backup_file = File.join(@backup_dir, "queue_backup_#{timestamp}_#{Time.now.to_f.to_s.split('.').last}.json")
+      end
+
+      snapshot = {
+        'timestamp' => Time.now.utc.iso8601,
+        'cleared_scope' => scope.to_s,
+        'count' => pending.size,
+        'pending' => pending,
+        'submitted' => submitted,
+        'failed' => failed,
+        'daily_quota_used' => @state['daily_quota_used'] || 0,
+        'last_reset_date' => @state['last_reset_date']
+      }
+
+      File.write(backup_file, JSON.pretty_generate(snapshot))
+      backup_file
+    end
+
+    def clear(scope = :all, backup: true)
+      pending = @state['pending'] || []
+      count = pending.size
+      backup_file = backup ? backup(scope) : nil
+
       if scope == :pending
         @state['pending'] = []
       else
@@ -5452,6 +5519,8 @@ module GSC
         @state['failed'] = []
       end
       save_state
+
+      { count: count, backup_file: backup_file }
     end
 
     def process_batch(api, batch_size: 50, dry_run: false, delay_sec: 0.15)
@@ -9039,7 +9108,7 @@ COMMAND_REGISTRY = [
     commands: [
       { name: "inspect <url>", shortcut: nil, desc: "Live Google index check (coverage, canonical, date, robots.txt)", flags: ["-d"] },
       { name: "index <url>", shortcut: nil, desc: "Notify Googlebot to crawl/index URL immediately (URL_UPDATED)", flags: ["--dry-run"] },
-      { name: "index-batch [action]", shortcut: "ib", desc: "Automated 200 URL/day quota queue manager (add, run, status, clear)", flags: ["--batch-size", "--dry-run", "--json"] },
+      { name: "index-batch [action]", shortcut: "ib", desc: "Automated 200 URL/day quota queue manager (add, run, status, clear)", flags: ["--batch-size", "--dry-run", "--force", "--json"] },
       { name: "remove <url>", shortcut: nil, desc: "Notify Googlebot a page has been deleted (URL_DELETED)", flags: ["--dry-run"] },
       { name: "status <url>", shortcut: nil, desc: "Check Google Indexing API notification metadata", flags: [] },
       { name: "sitemaps-list", shortcut: nil, desc: "List registered XML sitemaps in Search Console", flags: ["-d"] },
@@ -21010,11 +21079,54 @@ module GSC
           end
 
         when 'clear', 'reset'
-          queue.clear(:all)
+          count = (queue.state['pending'] || []).size
+          if count == 0
+            if options[:json]
+              puts JSON.pretty_generate({ ok: true, message: 'Batch queue is already empty.', count: 0 })
+            else
+              puts "Batch queue is already empty."
+            end
+            return
+          end
+
+          unless options[:force]
+            if $stdin.tty?
+              $stdout.print "Are you sure you want to clear #{count} pending URLs from the batch queue? [y/N]: "
+              $stdout.flush
+              ans = $stdin.gets.to_s.strip.downcase
+              unless ans == 'y' || ans == 'yes'
+                if options[:json]
+                  puts JSON.pretty_generate({ ok: false, message: 'Clear aborted. Queue preserved.' })
+                else
+                  puts "Clear aborted. Queue preserved."
+                end
+                return
+              end
+            else
+              error_msg = "Error: 'gsc index-batch clear' requires '--force' in non-interactive environments to prevent accidental queue loss."
+              if options[:json]
+                puts JSON.pretty_generate({ error: error_msg })
+              else
+                puts error_msg
+              end
+              exit 1
+            end
+          end
+
+          res = queue.clear(:all, backup: true)
+          backup_path = res[:backup_file]
+          display_backup = backup_path ? backup_path.sub(/^#{Regexp.escape(Dir.home)}\/\.config\/gsc/, '~/.gsc').sub(/^#{Regexp.escape(Dir.home)}/, '~') : 'none'
+          cleared_count = res[:count] || count
+
           if options[:json]
-            puts JSON.pretty_generate({ ok: true, message: 'Queue cleared' })
+            puts JSON.pretty_generate({
+              ok: true,
+              message: "Queue cleared (#{cleared_count} items). Backup saved to #{display_backup}",
+              cleared_count: cleared_count,
+              backup_file: backup_path
+            })
           else
-            puts Color.c("🗑️  Indexing queue cleared.", Color::GREEN)
+            puts "Queue cleared (#{cleared_count} items). Backup saved to #{display_backup}"
           end
 
         else
@@ -21032,7 +21144,13 @@ module GSC
             puts "\nCommands:"
             puts "   • #{Color.c('gsc index-batch add <url|sitemap.xml|file.txt>', Color::CYAN)} - Enqueue URLs"
             puts "   • #{Color.c('gsc index-batch run [--batch-size 50] [--dry-run]', Color::CYAN)} - Process queue"
-            puts "   • #{Color.c('gsc index-batch clear', Color::CYAN)}                           - Reset queue"
+            puts "   • #{Color.c('gsc index-batch clear [--force]', Color::CYAN)}                   - Reset queue (safe wipe)"
+            puts ""
+            puts "🛡️  #{Color::BOLD}Queue Safety Guard:#{Color::RESET}"
+            puts "   • Prevents accidental queue loss from scripts, cron, or AI agents"
+            puts "   • Interactive: Prompts for confirmation [y/N] before clearing"
+            puts "   • Non-interactive / CI: Requires #{Color.c('--force', Color::YELLOW)} flag to proceed"
+            puts "   • Snapshot backup: Automatically saves a backup to ~/.gsc/backups/ before clearing"
             puts ""
           end
         end
@@ -22857,10 +22975,19 @@ module GSC
         fd = data[:field_data] || {}
         if fd.any?
           source_label = data[:field_source] == :origin ? "Domain-Wide Origin RUM" : "URL-Level RUM"
-          overall = data[:overall_category] || "UNKNOWN"
-          overall_col = overall == 'FAST' ? Color::GREEN : (overall == 'AVERAGE' ? Color::YELLOW : Color::RED)
+          assessment = data[:cwv_assessment] || data[:overall_category] || "UNKNOWN"
+          assessment_badge = case assessment
+          when 'PASSED', 'FAST'
+            Color.c("PASSED (All 3 Metrics Good)", Color::GREEN, Color::BOLD)
+          when 'NEEDS IMPROVEMENT', 'AVERAGE'
+            Color.c("NEEDS IMPROVEMENT", Color::YELLOW, Color::BOLD)
+          when 'POOR', 'SLOW', 'FAILED'
+            Color.c("FAILED (Poor Metrics Detected)", Color::RED, Color::BOLD)
+          else
+            Color.c(assessment, Color::YELLOW, Color::BOLD)
+          end
           puts "\n#{Color::BOLD}🌐 CrUX FIELD DATA (28-Day Real User Monitoring - #{source_label}):#{Color::RESET}"
-          puts "   • Core Web Vitals Status        : #{Color.c(overall, overall_col, Color::BOLD)}"
+          puts "   • Core Web Vitals Assessment    : #{assessment_badge}"
 
           if fd['LARGEST_CONTENTFUL_PAINT_MS']
             val = "#{(fd['LARGEST_CONTENTFUL_PAINT_MS'][:percentile].to_f / 1000).round(2)} s"
@@ -30016,10 +30143,19 @@ module GSC
       fd = data[:field_data] || {}
       if fd.any?
         source_label = data[:field_source] == :origin ? "Domain-Wide Origin RUM" : "URL-Level RUM"
-        overall = data[:overall_category] || "UNKNOWN"
-        overall_col = overall == 'FAST' ? Color::GREEN : (overall == 'AVERAGE' ? Color::YELLOW : Color::RED)
+        assessment = data[:cwv_assessment] || data[:overall_category] || "UNKNOWN"
+        assessment_badge = case assessment
+        when 'PASSED', 'FAST'
+          Color.c("PASSED (All 3 Metrics Good)", Color::GREEN, Color::BOLD)
+        when 'NEEDS IMPROVEMENT', 'AVERAGE'
+          Color.c("NEEDS IMPROVEMENT", Color::YELLOW, Color::BOLD)
+        when 'POOR', 'SLOW', 'FAILED'
+          Color.c("FAILED (Poor Metrics Detected)", Color::RED, Color::BOLD)
+        else
+          Color.c(assessment, Color::YELLOW, Color::BOLD)
+        end
         puts "\n#{Color::BOLD}🌐 CrUX FIELD DATA (28-Day Real User Monitoring - #{source_label}):#{Color::RESET}"
-        puts "   • Core Web Vitals Status        : #{Color.c(overall, overall_col, Color::BOLD)}"
+        puts "   • Core Web Vitals Assessment    : #{assessment_badge}"
 
         if fd['LARGEST_CONTENTFUL_PAINT_MS']
           val = "#{(fd['LARGEST_CONTENTFUL_PAINT_MS'][:percentile].to_f / 1000).round(2)} s"
@@ -31529,6 +31665,10 @@ module GSC
           options[:batch_size] = size
         end
 
+        opts.on('-f', '--force', '--yes', '-y', 'Bypass confirmation prompts (required for non-interactive queue clears)') do
+          options[:force] = true
+        end
+
         opts.on('--concurrency COUNT', Integer, 'Concurrent threads for multi-page site crawler (default: 5, max: 20)') do |c|
           options[:concurrency] = c
         end
@@ -32185,6 +32325,14 @@ module GSC
         Audit.run(command, target, extra, options)
         exit 0 unless options[:in_dashboard]
         return
+
+      when 'index-batch', 'queue', 'batch-index'
+        action = target.to_s.strip.downcase
+        if action != 'run' && action != 'process' && action != 'execute'
+          Indexing.run(command, target, extra, options, nil, nil, nil, nil)
+          exit 0 unless options[:in_dashboard]
+          return
+        end
       end
 
       # 7. Authenticated Commands (GSC / Indexing / Analytics / GA4)

data/lib/gsc/cli/audit.rb

@@ -170,10 +170,19 @@ module GSC
         fd = data[:field_data] || {}
         if fd.any?
           source_label = data[:field_source] == :origin ? "Domain-Wide Origin RUM" : "URL-Level RUM"
-          overall = data[:overall_category] || "UNKNOWN"
-          overall_col = overall == 'FAST' ? Color::GREEN : (overall == 'AVERAGE' ? Color::YELLOW : Color::RED)
+          assessment = data[:cwv_assessment] || data[:overall_category] || "UNKNOWN"
+          assessment_badge = case assessment
+          when 'PASSED', 'FAST'
+            Color.c("PASSED (All 3 Metrics Good)", Color::GREEN, Color::BOLD)
+          when 'NEEDS IMPROVEMENT', 'AVERAGE'
+            Color.c("NEEDS IMPROVEMENT", Color::YELLOW, Color::BOLD)
+          when 'POOR', 'SLOW', 'FAILED'
+            Color.c("FAILED (Poor Metrics Detected)", Color::RED, Color::BOLD)
+          else
+            Color.c(assessment, Color::YELLOW, Color::BOLD)
+          end
           puts "\n#{Color::BOLD}🌐 CrUX FIELD DATA (28-Day Real User Monitoring - #{source_label}):#{Color::RESET}"
-          puts "   • Core Web Vitals Status        : #{Color.c(overall, overall_col, Color::BOLD)}"
+          puts "   • Core Web Vitals Assessment    : #{assessment_badge}"
 
           if fd['LARGEST_CONTENTFUL_PAINT_MS']
             val = "#{(fd['LARGEST_CONTENTFUL_PAINT_MS'][:percentile].to_f / 1000).round(2)} s"

data/lib/gsc/cli/indexing.rb

@@ -226,11 +226,54 @@ module GSC
           end
 
         when 'clear', 'reset'
-          queue.clear(:all)
+          count = (queue.state['pending'] || []).size
+          if count == 0
+            if options[:json]
+              puts JSON.pretty_generate({ ok: true, message: 'Batch queue is already empty.', count: 0 })
+            else
+              puts "Batch queue is already empty."
+            end
+            return
+          end
+
+          unless options[:force]
+            if $stdin.tty?
+              $stdout.print "Are you sure you want to clear #{count} pending URLs from the batch queue? [y/N]: "
+              $stdout.flush
+              ans = $stdin.gets.to_s.strip.downcase
+              unless ans == 'y' || ans == 'yes'
+                if options[:json]
+                  puts JSON.pretty_generate({ ok: false, message: 'Clear aborted. Queue preserved.' })
+                else
+                  puts "Clear aborted. Queue preserved."
+                end
+                return
+              end
+            else
+              error_msg = "Error: 'gsc index-batch clear' requires '--force' in non-interactive environments to prevent accidental queue loss."
+              if options[:json]
+                puts JSON.pretty_generate({ error: error_msg })
+              else
+                puts error_msg
+              end
+              exit 1
+            end
+          end
+
+          res = queue.clear(:all, backup: true)
+          backup_path = res[:backup_file]
+          display_backup = backup_path ? backup_path.sub(/^#{Regexp.escape(Dir.home)}\/\.config\/gsc/, '~/.gsc').sub(/^#{Regexp.escape(Dir.home)}/, '~') : 'none'
+          cleared_count = res[:count] || count
+
           if options[:json]
-            puts JSON.pretty_generate({ ok: true, message: 'Queue cleared' })
+            puts JSON.pretty_generate({
+              ok: true,
+              message: "Queue cleared (#{cleared_count} items). Backup saved to #{display_backup}",
+              cleared_count: cleared_count,
+              backup_file: backup_path
+            })
           else
-            puts Color.c("🗑️  Indexing queue cleared.", Color::GREEN)
+            puts "Queue cleared (#{cleared_count} items). Backup saved to #{display_backup}"
           end
 
         else
@@ -248,7 +291,13 @@ module GSC
             puts "\nCommands:"
             puts "   • #{Color.c('gsc index-batch add <url|sitemap.xml|file.txt>', Color::CYAN)} - Enqueue URLs"
             puts "   • #{Color.c('gsc index-batch run [--batch-size 50] [--dry-run]', Color::CYAN)} - Process queue"
-            puts "   • #{Color.c('gsc index-batch clear', Color::CYAN)}                           - Reset queue"
+            puts "   • #{Color.c('gsc index-batch clear [--force]', Color::CYAN)}                   - Reset queue (safe wipe)"
+            puts ""
+            puts "🛡️  #{Color::BOLD}Queue Safety Guard:#{Color::RESET}"
+            puts "   • Prevents accidental queue loss from scripts, cron, or AI agents"
+            puts "   • Interactive: Prompts for confirmation [y/N] before clearing"
+            puts "   • Non-interactive / CI: Requires #{Color.c('--force', Color::YELLOW)} flag to proceed"
+            puts "   • Snapshot backup: Automatically saves a backup to ~/.gsc/backups/ before clearing"
             puts ""
           end
         end

data/lib/gsc/cli.rb

@@ -134,6 +134,10 @@ module GSC
           options[:batch_size] = size
         end
 
+        opts.on('-f', '--force', '--yes', '-y', 'Bypass confirmation prompts (required for non-interactive queue clears)') do
+          options[:force] = true
+        end
+
         opts.on('--concurrency COUNT', Integer, 'Concurrent threads for multi-page site crawler (default: 5, max: 20)') do |c|
           options[:concurrency] = c
         end
@@ -790,6 +794,14 @@ module GSC
         Audit.run(command, target, extra, options)
         exit 0 unless options[:in_dashboard]
         return
+
+      when 'index-batch', 'queue', 'batch-index'
+        action = target.to_s.strip.downcase
+        if action != 'run' && action != 'process' && action != 'execute'
+          Indexing.run(command, target, extra, options, nil, nil, nil, nil)
+          exit 0 unless options[:in_dashboard]
+          return
+        end
       end
 
       # 7. Authenticated Commands (GSC / Indexing / Analytics / GA4)

data/lib/gsc/cli_advanced.rb

@@ -180,10 +180,19 @@ module GSC
       fd = data[:field_data] || {}
       if fd.any?
         source_label = data[:field_source] == :origin ? "Domain-Wide Origin RUM" : "URL-Level RUM"
-        overall = data[:overall_category] || "UNKNOWN"
-        overall_col = overall == 'FAST' ? Color::GREEN : (overall == 'AVERAGE' ? Color::YELLOW : Color::RED)
+        assessment = data[:cwv_assessment] || data[:overall_category] || "UNKNOWN"
+        assessment_badge = case assessment
+        when 'PASSED', 'FAST'
+          Color.c("PASSED (All 3 Metrics Good)", Color::GREEN, Color::BOLD)
+        when 'NEEDS IMPROVEMENT', 'AVERAGE'
+          Color.c("NEEDS IMPROVEMENT", Color::YELLOW, Color::BOLD)
+        when 'POOR', 'SLOW', 'FAILED'
+          Color.c("FAILED (Poor Metrics Detected)", Color::RED, Color::BOLD)
+        else
+          Color.c(assessment, Color::YELLOW, Color::BOLD)
+        end
         puts "\n#{Color::BOLD}🌐 CrUX FIELD DATA (28-Day Real User Monitoring - #{source_label}):#{Color::RESET}"
-        puts "   • Core Web Vitals Status        : #{Color.c(overall, overall_col, Color::BOLD)}"
+        puts "   • Core Web Vitals Assessment    : #{assessment_badge}"
 
         if fd['LARGEST_CONTENTFUL_PAINT_MS']
           val = "#{(fd['LARGEST_CONTENTFUL_PAINT_MS'][:percentile].to_f / 1000).round(2)} s"

data/lib/gsc/command_registry.rb

@@ -58,7 +58,7 @@ COMMAND_REGISTRY = [
     commands: [
       { name: "inspect <url>", shortcut: nil, desc: "Live Google index check (coverage, canonical, date, robots.txt)", flags: ["-d"] },
       { name: "index <url>", shortcut: nil, desc: "Notify Googlebot to crawl/index URL immediately (URL_UPDATED)", flags: ["--dry-run"] },
-      { name: "index-batch [action]", shortcut: "ib", desc: "Automated 200 URL/day quota queue manager (add, run, status, clear)", flags: ["--batch-size", "--dry-run", "--json"] },
+      { name: "index-batch [action]", shortcut: "ib", desc: "Automated 200 URL/day quota queue manager (add, run, status, clear)", flags: ["--batch-size", "--dry-run", "--force", "--json"] },
       { name: "remove <url>", shortcut: nil, desc: "Notify Googlebot a page has been deleted (URL_DELETED)", flags: ["--dry-run"] },
       { name: "status <url>", shortcut: nil, desc: "Check Google Indexing API notification metadata", flags: [] },
       { name: "sitemaps-list", shortcut: nil, desc: "List registered XML sitemaps in Search Console", flags: ["-d"] },

data/lib/gsc/config.rb

@@ -9,7 +9,13 @@ module GSC
     CONFIG_DIR  = File.expand_path('~/.config/gsc')
     CONFIG_FILE = File.join(CONFIG_DIR, 'config.json')
 
-def self.get(key)
+    def self.ensure_gsc_symlink!
+      gsc_dir = File.expand_path('~/.gsc')
+      return if File.exist?(gsc_dir) || File.symlink?(gsc_dir)
+      File.symlink(CONFIG_DIR, gsc_dir) rescue nil
+    end
+
+    def self.get(key)
   load[key.to_s]
 end
 

data/lib/gsc/indexing_queue.rb

@@ -8,13 +8,16 @@ require 'time'
 module GSC
   class IndexingQueue
     QUEUE_FILE = File.join(Config::CONFIG_DIR, 'indexing_queue.json')
+    BACKUPS_DIR = File.join(Config::CONFIG_DIR, 'backups')
     DAILY_LIMIT = 200
 
-    attr_reader :state
+    attr_reader :state, :file_path, :backup_dir
 
-    def initialize(file_path = QUEUE_FILE)
+    def initialize(file_path = QUEUE_FILE, backup_dir: nil)
       @file_path = file_path
+      @backup_dir = backup_dir || File.join(File.dirname(@file_path), 'backups')
       @state = load_state
+      Config.ensure_gsc_symlink!
     end
 
     def add_urls(urls)
@@ -46,7 +49,41 @@ module GSC
       }
     end
 
-    def clear(scope = :all)
+    def backup(scope = :all)
+      pending = @state['pending'] || []
+      submitted = @state['submitted'] || []
+      failed = @state['failed'] || []
+
+      # Nothing to backup if completely empty
+      return nil if pending.empty? && submitted.empty? && failed.empty?
+
+      FileUtils.mkdir_p(@backup_dir)
+      timestamp = Time.now.utc.strftime('%Y%m%d_%H%M%S')
+      backup_file = File.join(@backup_dir, "queue_backup_#{timestamp}.json")
+      if File.exist?(backup_file)
+        backup_file = File.join(@backup_dir, "queue_backup_#{timestamp}_#{Time.now.to_f.to_s.split('.').last}.json")
+      end
+
+      snapshot = {
+        'timestamp' => Time.now.utc.iso8601,
+        'cleared_scope' => scope.to_s,
+        'count' => pending.size,
+        'pending' => pending,
+        'submitted' => submitted,
+        'failed' => failed,
+        'daily_quota_used' => @state['daily_quota_used'] || 0,
+        'last_reset_date' => @state['last_reset_date']
+      }
+
+      File.write(backup_file, JSON.pretty_generate(snapshot))
+      backup_file
+    end
+
+    def clear(scope = :all, backup: true)
+      pending = @state['pending'] || []
+      count = pending.size
+      backup_file = backup ? backup(scope) : nil
+
       if scope == :pending
         @state['pending'] = []
       else
@@ -55,6 +92,8 @@ module GSC
         @state['failed'] = []
       end
       save_state
+
+      { count: count, backup_file: backup_file }
     end
 
     def process_batch(api, batch_size: 50, dry_run: false, delay_sec: 0.15)

data/lib/gsc/page_speed.rb

@@ -86,6 +86,29 @@ module GSC
 
       overall_category = data.dig('loadingExperience', 'overall_category') || data.dig('originLoadingExperience', 'overall_category')
 
+      # Official Google Core Web Vitals Assessment evaluates ONLY the 3 Core Web Vitals:
+      # LCP, INP (or legacy FID), and CLS. (FCP and TTFB are diagnostic metrics).
+      # - PASSED: All present CWV metrics are 'FAST' (Good).
+      # - POOR: Any CWV metric is 'SLOW' (Poor).
+      # - NEEDS IMPROVEMENT: No CWV metric is 'SLOW', but at least one is 'AVERAGE'.
+      cwv_keys = ['LARGEST_CONTENTFUL_PAINT_MS', 'INTERACTION_TO_NEXT_PAINT', 'CUMULATIVE_LAYOUT_SHIFT_SCORE']
+      cwv_keys[1] = 'FIRST_INPUT_DELAY_MS' if !crux_metrics.key?('INTERACTION_TO_NEXT_PAINT') && crux_metrics.key?('FIRST_INPUT_DELAY_MS')
+
+      active_cwv = cwv_keys.map { |k| crux_metrics[k] }.compact
+      cwv_assessment = if active_cwv.any?
+        if active_cwv.any? { |m| m[:category] == 'SLOW' }
+          'POOR'
+        elsif active_cwv.any? { |m| m[:category] == 'AVERAGE' }
+          'NEEDS IMPROVEMENT'
+        elsif active_cwv.all? { |m| m[:category] == 'FAST' }
+          'PASSED'
+        else
+          overall_category
+        end
+      else
+        overall_category
+      end
+
       # Opportunities
       opportunities = []
       audits.each do |k, v|
@@ -117,6 +140,7 @@ module GSC
         field_data: crux_metrics,
         field_source: crux_source,
         overall_category: overall_category,
+        cwv_assessment: cwv_assessment,
         opportunities: opportunities.first(5)
       }
     end

data/lib/gsc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GSC
-  VERSION = '2.2.3'
+  VERSION = '2.2.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gsc-cli
 version: !ruby/object:Gem::Version
-  version: 2.2.3
+  version: 2.2.5
 platform: ruby
 authors:
 - ApollosWave LLC