raygatherer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aef304a404bc427e2d066db7cf8767e73d06dc8c765b15f18b78afc68a78ee1e
-  data.tar.gz: e81748ac2ce4443e5a30ff55e63727db50148d7b1402ffebbee280c01f19a8a6
+  metadata.gz: a9324c6a164aa329514f237d51e7942f8d2399e698fcb500de86440aef9320f0
+  data.tar.gz: 5412fc1973d54829b42684ea37d73df8ab4cf6a85a2ecfd2b1248e9c45833817
 SHA512:
-  metadata.gz: cc2ce523698c34711223d9c88a14360f98850e91650da419acb9b532e6d1e5a8f1bc8db47d418e83acf648878803a4f2811ca65403dbfcbfae071017e0ad6c3b
-  data.tar.gz: bde55ec5165b8516d9e6295a2b6215db2c54f2399b9c299497591b9d0ebe212a1d2eac19c0d10ace5324816f1a37f477ca06587125110a858488c39a587f283d
+  metadata.gz: e34d2c21750b31b1d0e33c8334233748b6d7aca62eb6879912226e644f8cc7f2076b815937a3f05b1853595b8aa28f25b61ae06f5e3e13d0ce8fe794ee58fe73
+  data.tar.gz: e7e7c1bbb88a75a9b588713dfec1692fcbf2f9e0bbf126a82dc517b86d1d7279cf48ccd8a3e1fba7b210d89e2507d64777ca17b14617fba88e9bc52e27aa80f7

data/README.md

@@ -12,27 +12,36 @@ Currently implemented:
 
 - alerts from live analysis, with severity-based exit codes
 - recording list/start/stop/delete/download
-- system stats
+- analysis report for named or active recordings
 - analysis queue status and triggering analysis runs
+- system stats and raw log output
+- device clock show and sync
 - config show/set/test-notification
 - JSON output mode for scriptable commands
 - optional basic auth and config file support
+- debug utilities (display-state)
 
 ## Installation
 
-### Ruby version
+### Via RubyGems
 
-`raygatherer` requires Ruby `>= 3.1.0`.
+```bash
+gem install raygatherer
+```
 
-### Install from this repo
+Requires Ruby >= 3.2.
+
+### From source
 
 ```bash
+git clone https://github.com/mjstallard/raygatherer.git
+cd raygatherer
 bundle install
 make build
 make install
 ```
 
-Or install directly with RubyGems:
+Or build and install the gem directly:
 
 ```bash
 gem build raygatherer.gemspec
@@ -50,37 +59,49 @@ raygatherer --help
 Check live alerts:
 
 ```bash
-raygatherer --host http://rayhunter.local alerts
+raygatherer --host http://192.168.1.1 alerts
 ```
 
 Check live alerts as JSON:
 
 ```bash
-raygatherer --host http://rayhunter.local --json alerts
+raygatherer --host http://192.168.1.1 --json alerts
 ```
 
 List recordings:
 
 ```bash
-raygatherer --host http://rayhunter.local recording list
+raygatherer --host http://192.168.1.1 recording list
 ```
 
 Download a recording:
 
 ```bash
-raygatherer --host http://rayhunter.local recording download 1738950000
+raygatherer --host http://192.168.1.1 recording download 1738950000
+```
+
+Show analysis report for a recording:
+
+```bash
+raygatherer --host http://192.168.1.1 analysis report 1738950000
+```
+
+Show analysis report for the active recording:
+
+```bash
+raygatherer --host http://192.168.1.1 analysis report --live
 ```
 
 Show analysis queue status:
 
 ```bash
-raygatherer --host http://rayhunter.local analysis status
+raygatherer --host http://192.168.1.1 analysis status
 ```
 
 Show system stats:
 
 ```bash
-raygatherer --host http://rayhunter.local stats
+raygatherer --host http://192.168.1.1 stats
 ```
 
 ## Global Flags
@@ -113,7 +134,7 @@ CLI flags always override config values.
 Example:
 
 ```yaml
-host: http://rayhunter.local
+host: http://192.168.1.1
 basic_auth_user: admin
 basic_auth_password: replace-me
 json: false
@@ -126,16 +147,21 @@ Main commands:
 
 - `alerts`
 - `recording list`
-- `recording download <name> [--qmdl|--pcap|--zip] [--download-dir DIR|--save-as PATH]`
-- `recording delete <name>`
-- `recording stop`
 - `recording start`
+- `recording stop`
+- `recording download <name> [--qmdl|--pcap|--zip] [--download-dir DIR|--save-as PATH]`
+- `recording delete <name> | --all [--force]`
 - `analysis status`
-- `analysis run [NAME|--all]`
+- `analysis run <name> | --all`
+- `analysis report <name> | --live`
+- `time show`
+- `time sync`
 - `config show`
 - `config set` (reads JSON from stdin)
 - `config test-notification`
 - `stats`
+- `log`
+- `debug display-state <recording|paused|warning> [--severity low|medium|high]`
 
 For command-specific help:
 
@@ -164,7 +190,7 @@ raygatherer analysis run --help
 Example:
 
 ```bash
-raygatherer --host http://rayhunter.local alerts
+raygatherer --host http://192.168.1.1 alerts
 code=$?
 [ "$code" -ge 11 ] && echo "medium or high alert"
 ```
@@ -176,7 +202,7 @@ Commands that support `--json` return machine-readable output to `stdout`. This
 Example:
 
 ```bash
-raygatherer --host http://rayhunter.local --json config show | jq '.analyzers'
+raygatherer --host http://192.168.1.1 --json config show | jq '.analyzers'
 ```
 
 ## Development

data/lib/raygatherer/api_client.rb

@@ -73,10 +73,33 @@ module Raygatherer
       end
     end
 
+    def fetch_time
+      get("/api/time") do |body|
+        parse_json(body)
+      end
+    end
+
+    def set_time_offset(offset_seconds)
+      post("/api/time-offset", expected_code: "200",
+        body: ::JSON.generate({offset_seconds: offset_seconds}),
+        content_type: "application/json")
+    end
+
+    def fetch_log
+      get("/api/log") do |body|
+        log_verbose "Received log (#{body.bytesize} bytes)"
+        body
+      end
+    end
+
     def test_notification
       post("/api/test-notification", expected_code: "200")
     end
 
+    def set_display_state(body_json)
+      post("/api/debug/display-state", body: body_json, content_type: "application/json", expected_code: "200")
+    end
+
     def set_config(json_body)
       post("/api/config", body: json_body, content_type: "application/json")
     end
@@ -95,6 +118,10 @@ module Raygatherer
       post("/api/delete-recording/#{URI.encode_www_form_component(name)}")
     end
 
+    def delete_all_recordings
+      post("/api/delete-all-recordings")
+    end
+
     def start_analysis(name)
       encoded = URI.encode_www_form_component(name)
       body = post("/api/analysis/#{encoded}")
@@ -256,11 +283,10 @@ module Raygatherer
     end
 
     def normalize_host(host)
-      # Add http:// if no scheme is present
-      if !%r{^https?://}.match?(host)
-        "http://#{host}"
-      else
+      if %r{^https?://}.match?(host)
         host
+      else
+        "http://#{host}"
       end
     end
   end

data/lib/raygatherer/cli.rb

@@ -16,6 +16,7 @@ module Raygatherer
     end
 
     ROUTES = {
+      ["log", nil] => {file: "commands/log", klass: "Commands::Log", json: false},
       ["stats", nil] => {file: "commands/stats", klass: "Commands::Stats", json: true},
       ["alerts", nil] => {file: "commands/alerts", klass: "Commands::Alerts", json: true},
       ["recording", "list"] => {file: "commands/recording/list", klass: "Commands::Recording::List", json: true},
@@ -25,9 +26,13 @@ module Raygatherer
       ["recording", "start"] => {file: "commands/recording/start", klass: "Commands::Recording::Start", json: false},
       ["analysis", "status"] => {file: "commands/analysis/status", klass: "Commands::Analysis::Status", json: true},
       ["analysis", "run"] => {file: "commands/analysis/run", klass: "Commands::Analysis::Run", json: true},
+      ["analysis", "report"] => {file: "commands/analysis/report", klass: "Commands::Analysis::Report", json: true},
       ["config", "show"] => {file: "commands/config/show", klass: "Commands::Config::Show", json: true},
       ["config", "set"] => {file: "commands/config/set", klass: "Commands::Config::Set", json: false},
-      ["config", "test-notification"] => {file: "commands/config/test_notification", klass: "Commands::Config::TestNotification", json: false}
+      ["config", "test-notification"] => {file: "commands/config/test_notification", klass: "Commands::Config::TestNotification", json: false},
+      ["debug", "display-state"] => {file: "commands/debug/display_state", klass: "Commands::Debug::DisplayState", json: false},
+      ["time", "show"] => {file: "commands/time/show", klass: "Commands::Time::Show", json: true},
+      ["time", "sync"] => {file: "commands/time/sync", klass: "Commands::Time::Sync", json: false}
     }.freeze
 
     def self.run(argv, stdout: $stdout, stderr: $stderr, config: Config.new)
@@ -44,8 +49,8 @@ module Raygatherer
 
     def run
       # Extract global flags BEFORE processing
-      cli_verbose = @argv.delete("--verbose") ? true : nil
-      cli_json = @argv.delete("--json") ? true : nil
+      cli_verbose = extract_boolean_flag("--verbose")
+      cli_json = extract_boolean_flag("--json")
       cli_host = extract_value_flag("--host")
       cli_username = extract_value_flag("--basic-auth-user")
       cli_password = extract_value_flag("--basic-auth-password")
@@ -145,11 +150,14 @@ module Raygatherer
       name.split("::").reduce(Raygatherer) { |mod, part| mod.const_get(part) }
     end
 
+    def extract_boolean_flag(flag)
+      @argv.delete(flag) ? true : nil
+    end
+
     def extract_value_flag(flag)
       index = @argv.index(flag)
       return nil unless index
-      @argv.delete_at(index) # remove the flag
-      @argv.delete_at(index) # remove the value (shifted into same index)
+      @argv.slice!(index, 2)&.last
     end
 
     def show_help(output = @stdout)
@@ -174,9 +182,14 @@ module Raygatherer
       output.puts "    analysis status                   Show analysis queue status"
       output.puts "    analysis run <name>               Queue a recording for analysis"
       output.puts "    analysis run --all                Queue all recordings for analysis"
+      output.puts "    analysis report <name>            Show the full analysis report for a recording"
       output.puts "    config show                       Show device configuration"
       output.puts "    config set                        Update device configuration (reads JSON from stdin)"
       output.puts "    config test-notification          Send a test notification"
+      output.puts "    debug display-state STATE         Set device display state (recording, paused, warning)"
+      output.puts "    time show                        Show device time (system, adjusted, offset)"
+      output.puts "    time sync                        Sync device clock to this machine's time"
+      output.puts "    log                              Download the device log"
       output.puts "    stats                            Show device system stats"
       output.puts ""
       output.puts "Configuration:"

data/lib/raygatherer/commands/alerts.rb

@@ -3,7 +3,8 @@
 require "optparse"
 require "time"
 require_relative "base"
-require_relative "../formatters/json"
+require_relative "../formatters/alerts_json"
+require_relative "../formatters/alerts_human"
 
 module Raygatherer
   module Commands
@@ -41,7 +42,7 @@ module Raygatherer
           alerts = filter_latest(alerts, data[:rows]) if @latest
 
           # Select formatter based on --json flag
-          formatter = @json ? Formatters::JSON.new : Formatters::Human.new
+          formatter = @json ? Formatters::AlertsJSON.new : Formatters::AlertsHuman.new
           @stdout.puts formatter.format(alerts)
 
           # Return severity-based exit code
@@ -105,13 +106,13 @@ module Raygatherer
       end
 
       def parse_timestamp(str)
-        Time.parse(str)
+        ::Time.parse(str)
       rescue ArgumentError
         raise ArgumentError, "invalid timestamp: #{str}"
       end
 
       def filter_after(alerts)
-        alerts.select { |a| a[:packet_timestamp] && Time.parse(a[:packet_timestamp]) > @after }
+        alerts.select { |a| a[:packet_timestamp] && ::Time.parse(a[:packet_timestamp]) > @after }
       end
 
       def filter_latest(alerts, rows)

data/lib/raygatherer/commands/analysis/report.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../base"
+require_relative "../../formatters/analysis_report_json"
+require_relative "../../formatters/analysis_report_human"
+
+module Raygatherer
+  module Commands
+    module Analysis
+      class Report < Base
+        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
+          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
+          @json = json
+          @live = false
+        end
+
+        def run
+          with_error_handling do
+            parse_options
+
+            name = @argv.shift
+
+            if @live && name
+              @stderr.puts "Error: cannot use --live with a recording name"
+              return EXIT_CODE_ERROR
+            end
+
+            if !@live && name.nil?
+              @stderr.puts "Error: recording name or --live is required"
+              return EXIT_CODE_ERROR
+            end
+
+            data = @live ? @api_client.fetch_live_analysis_report : @api_client.fetch_analysis_report(name)
+
+            formatter = @json ? Formatters::AnalysisReportJSON.new : Formatters::AnalysisReportHuman.new
+            @stdout.puts formatter.format(data)
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer analysis report [options] NAME"
+            opts.separator ""
+            opts.separator "Options:"
+
+            opts.on("--live", "Show analysis report for the currently active recording") do
+              @live = true
+            end
+
+            opts.on("-h", "--help", "Show this help message") do
+              show_help
+              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+            end
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] analysis report [options] [NAME]"
+          output.puts ""
+          output.puts "Show the full analysis report for a named recording, or the active recording."
+          output.puts ""
+          output.puts "Options:"
+          output.puts "        --live                           Show analysis report for the currently active recording"
+          output.puts "    -h, --help                           Show this help message"
+          output.puts ""
+          print_global_options(output, json: true)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 analysis report 1738950000"
+          output.puts "  raygatherer --host http://rayhunter --json analysis report 1738950000"
+          output.puts "  raygatherer --host http://rayhunter analysis report --live"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/analysis/run.rb

@@ -31,7 +31,7 @@ module Raygatherer
               return EXIT_CODE_ERROR
             end
 
-            status = @api_client.start_analysis(@all ? "" : name)
+            status = @all ? run_all : @api_client.start_analysis(name)
 
             formatter = @json ? Formatters::AnalysisStatusJSON.new : Formatters::AnalysisStatusHuman.new
             @stdout.puts formatter.format(status)
@@ -42,6 +42,13 @@ module Raygatherer
 
         private
 
+        def run_all
+          manifest = @api_client.fetch_manifest
+          names = manifest["entries"].map { |e| e["name"] }
+          names.each { |name| @api_client.start_analysis(name) }
+          @api_client.fetch_analysis_status
+        end
+
         def parse_options
           OptionParser.new do |opts|
             opts.banner = "Usage: raygatherer analysis run [options] [NAME]"

data/lib/raygatherer/commands/debug/display_state.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../base"
+
+module Raygatherer
+  module Commands
+    module Debug
+      class DisplayState < Base
+        VALID_STATES = %w[recording paused warning].freeze
+        VALID_SEVERITIES = %w[low medium high].freeze
+
+        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil)
+          super
+          @severity = nil
+        end
+
+        def run
+          with_error_handling do
+            parse_options
+
+            state = @argv.shift
+
+            unless VALID_STATES.include?(state)
+              @stderr.puts "Error: state must be one of: #{VALID_STATES.join(", ")}"
+              return EXIT_CODE_ERROR
+            end
+
+            if state == "warning" && @severity.nil?
+              @stderr.puts "Error: --severity is required when state is 'warning'"
+              return EXIT_CODE_ERROR
+            end
+
+            if state != "warning" && !@severity.nil?
+              @stderr.puts "Error: --severity is only valid when state is 'warning'"
+              return EXIT_CODE_ERROR
+            end
+
+            @api_client.set_display_state(build_body(state))
+            @stdout.puts "Display state updated."
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def build_body(state)
+          case state
+          when "recording" then JSON.generate("Recording")
+          when "paused" then JSON.generate("Paused")
+          when "warning" then JSON.generate({"WarningDetected" => {"event_type" => @severity.capitalize}})
+          end
+        end
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer debug display-state [options] STATE"
+            opts.separator ""
+            opts.separator "Options:"
+
+            opts.on("--severity LEVEL", VALID_SEVERITIES, "Severity: low, medium, high (required for 'warning' state)") do |s|
+              @severity = s
+            end
+
+            opts.on("-h", "--help", "Show this help message") do
+              show_help
+              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+            end
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] debug display-state [options] STATE"
+          output.puts ""
+          output.puts "Change the display state of the device for debugging purposes."
+          output.puts ""
+          output.puts "States:"
+          output.puts "    recording                        Device is recording, no warnings"
+          output.puts "    paused                           Device is not recording"
+          output.puts "    warning                          Warning detected (requires --severity)"
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    --severity LEVEL                 Warning severity: low, medium, high"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 debug display-state recording"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 debug display-state paused"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 debug display-state warning --severity high"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/log.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "base"
+
+module Raygatherer
+  module Commands
+    class Log < Base
+      def run
+        with_error_handling do
+          parse_options
+          @stdout.print @api_client.fetch_log
+          EXIT_CODE_SUCCESS
+        end
+      end
+
+      private
+
+      def parse_options
+        OptionParser.new do |opts|
+          opts.on("-h", "--help", "Show this help message") do
+            show_help
+            raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+          end
+        end.parse!(@argv)
+      end
+
+      def show_help(output = @stdout)
+        output.puts "Usage: raygatherer [global options] log [options]"
+        output.puts ""
+        output.puts "Options:"
+        output.puts "    -h, --help                       Show this help message"
+        output.puts ""
+        print_global_options(output)
+        output.puts ""
+        output.puts "Examples:"
+        output.puts "  raygatherer --host http://192.168.1.100:8080 log"
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/recording/delete.rb

@@ -7,30 +7,71 @@ module Raygatherer
   module Commands
     module Recording
       class Delete < Base
+        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, stdin: $stdin, **_kwargs)
+          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
+          @stdin = stdin
+          @all = false
+          @force = false
+        end
+
         def run
           with_error_handling do
             parse_options
 
-            name = @argv.shift
-            unless name
-              @stderr.puts "Error: recording name is required"
+            if @all && !@argv.empty?
+              @stderr.puts "Error: cannot specify both a recording name and --all"
               next EXIT_CODE_ERROR
             end
 
-            @api_client.delete_recording(name)
-            @stdout.puts "Deleted recording: #{name}"
-            EXIT_CODE_SUCCESS
+            if @all
+              delete_all
+            else
+              delete_named
+            end
           end
         end
 
         private
 
+        def delete_all
+          unless @force
+            @stderr.print "Warning: This will permanently delete ALL recordings!\nAre you sure? [y/N]: "
+            response = @stdin.gets&.strip&.downcase || ""
+            unless response == "y" || response == "yes"
+              @stderr.puts "Aborted."
+              return EXIT_CODE_ERROR
+            end
+          end
+          @api_client.delete_all_recordings
+          @stdout.puts "Deleted all recordings."
+          EXIT_CODE_SUCCESS
+        end
+
+        def delete_named
+          name = @argv.shift
+          unless name
+            @stderr.puts "Error: recording name or --all is required"
+            return EXIT_CODE_ERROR
+          end
+          @api_client.delete_recording(name)
+          @stdout.puts "Deleted recording: #{name}"
+          EXIT_CODE_SUCCESS
+        end
+
         def parse_options
           OptionParser.new do |opts|
-            opts.banner = "Usage: raygatherer recording delete <name>"
+            opts.banner = "Usage: raygatherer recording delete <name> | --all [--force]"
             opts.separator ""
             opts.separator "Options:"
 
+            opts.on("--all", "Delete all recordings (prompts for confirmation)") do
+              @all = true
+            end
+
+            opts.on("-f", "--force", "Skip confirmation prompt (use with --all)") do
+              @force = true
+            end
+
             opts.on("-h", "--help", "Show this help message") do
               show_help
               raise CLI::EarlyExit, EXIT_CODE_SUCCESS
@@ -40,14 +81,20 @@ module Raygatherer
 
         def show_help(output = @stdout)
           output.puts "Usage: raygatherer [global options] recording delete <name>"
+          output.puts "       raygatherer [global options] recording delete --all [--force]"
           output.puts ""
           output.puts "Options:"
+          output.puts "    --all                            Delete all recordings (prompts for confirmation)"
+          output.puts "    -f, --force                      Skip confirmation prompt (use with --all)"
           output.puts "    -h, --help                       Show this help message"
           output.puts ""
           print_global_options(output)
           output.puts ""
           output.puts "Examples:"
           output.puts "  raygatherer --host http://192.168.1.100:8080 recording delete 1738950000"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 recording delete --all"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 recording delete --all --force"
+          output.puts "  echo y | raygatherer --host http://192.168.1.100:8080 recording delete --all"
         end
       end
     end

data/lib/raygatherer/commands/recording/download.rb

@@ -28,21 +28,21 @@ module Raygatherer
         def run
           with_error_handling do
             parse_options
-            next EXIT_CODE_ERROR unless validate_format_flags
-            next EXIT_CODE_ERROR unless validate_path_flags
+            return EXIT_CODE_ERROR unless validate_format_flags
+            return EXIT_CODE_ERROR unless validate_path_flags
 
             name = @argv.shift
             unless name
               @stderr.puts "Error: recording name is required"
-              next EXIT_CODE_ERROR
+              return EXIT_CODE_ERROR
             end
 
             dest_path = resolve_destination(name)
-            next EXIT_CODE_ERROR unless dest_path
+            return EXIT_CODE_ERROR unless dest_path
 
             if File.exist?(dest_path)
               @stderr.puts "Error: file already exists: #{dest_path}"
-              next EXIT_CODE_ERROR
+              return EXIT_CODE_ERROR
             end
 
             spinner = Spinner.new(stderr: @stderr)

data/lib/raygatherer/commands/recording/start.rb

@@ -13,7 +13,7 @@ module Raygatherer
 
             if @argv.any?
               @stderr.puts "Error: recording start does not take a name"
-              next EXIT_CODE_ERROR
+              return EXIT_CODE_ERROR
             end
 
             @api_client.start_recording

data/lib/raygatherer/commands/recording/stop.rb

@@ -13,7 +13,7 @@ module Raygatherer
 
             if @argv.any?
               @stderr.puts "Error: recording stop does not take a name"
-              next EXIT_CODE_ERROR
+              return EXIT_CODE_ERROR
             end
 
             @api_client.stop_recording

data/lib/raygatherer/commands/time/show.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../base"
+require_relative "../../formatters/time_json"
+require_relative "../../formatters/time_human"
+
+module Raygatherer
+  module Commands
+    module Time
+      class Show < Base
+        def initialize(argv, stdout: $stdout, stderr: $stderr, api_client: nil, json: false)
+          super(argv, stdout: stdout, stderr: stderr, api_client: api_client)
+          @json = json
+        end
+
+        def run
+          with_error_handling do
+            parse_options
+
+            time = @api_client.fetch_time
+
+            formatter = @json ? Formatters::TimeJSON.new : Formatters::TimeHuman.new
+            @stdout.puts formatter.format(time)
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer time show [options]"
+            opts.separator ""
+            opts.separator "Options:"
+
+            opts.on("-h", "--help", "Show this help message") do
+              show_help
+              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+            end
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] time show [options]"
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output, json: true)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 time show"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 --json time show"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/commands/time/sync.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+require_relative "../base"
+
+module Raygatherer
+  module Commands
+    module Time
+      class Sync < Base
+        def run
+          with_error_handling do
+            parse_options
+
+            time_data = @api_client.fetch_time
+            device_system_time = ::Time.parse(time_data["system_time"])
+            offset = (::Time.now - device_system_time).round
+            @api_client.set_time_offset(offset)
+            @stdout.puts "Clock synced. Offset: #{offset}s"
+
+            EXIT_CODE_SUCCESS
+          end
+        end
+
+        private
+
+        def parse_options
+          OptionParser.new do |opts|
+            opts.banner = "Usage: raygatherer time sync"
+            opts.separator ""
+            opts.separator "Options:"
+
+            opts.on("-h", "--help", "Show this help message") do
+              show_help
+              raise CLI::EarlyExit, EXIT_CODE_SUCCESS
+            end
+          end.parse!(@argv)
+        end
+
+        def show_help(output = @stdout)
+          output.puts "Usage: raygatherer [global options] time sync"
+          output.puts ""
+          output.puts "Syncs the device clock to this machine's time."
+          output.puts ""
+          output.puts "Options:"
+          output.puts "    -h, --help                       Show this help message"
+          output.puts ""
+          print_global_options(output)
+          output.puts ""
+          output.puts "Examples:"
+          output.puts "  raygatherer --host http://192.168.1.100:8080 time sync"
+        end
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/{human.rb → alerts_human.rb}

@@ -2,7 +2,7 @@
 
 module Raygatherer
   module Formatters
-    class Human
+    class AlertsHuman
       def format(alerts)
         if alerts.empty?
           colorize("✓ No alerts detected", :green)

data/lib/raygatherer/formatters/{json.rb → alerts_json.rb}

@@ -4,7 +4,7 @@ require "json"
 
 module Raygatherer
   module Formatters
-    class JSON
+    class AlertsJSON
       def format(alerts)
         output = alerts.map do |alert|
           {
@@ -15,7 +15,7 @@ module Raygatherer
           }
         end
 
-        ::JSON.generate(output)
+        JSON.generate(output)
       end
     end
   end

data/lib/raygatherer/formatters/analysis_report_human.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Raygatherer
+  module Formatters
+    class AnalysisReportHuman
+      def format(data)
+        metadata = data[:metadata] || {}
+        rows = data[:rows] || []
+
+        lines = []
+        lines << format_header(metadata)
+        lines << format_analyzers(metadata)
+        lines << ""
+
+        rows.each do |row|
+          lines.concat(format_row(row, metadata))
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def format_header(metadata)
+        rayhunter = metadata["rayhunter"] || {}
+        version = rayhunter["rayhunter_version"]
+        os = rayhunter["system_os"]
+        arch = rayhunter["arch"]
+        report_version = metadata["report_version"]
+
+        parts = []
+        parts << "Rayhunter v#{version}" if version
+        os_arch = [os, arch].compact.join(" ")
+        parts << os_arch unless os_arch.empty?
+        parts << "Report version #{report_version}" if report_version
+
+        parts.join("  |  ")
+      end
+
+      def format_analyzers(metadata)
+        analyzers = metadata["analyzers"] || []
+        return "Analyzers: (none)" if analyzers.empty?
+
+        names = analyzers.filter_map do |a|
+          next unless a
+          v = a["version"] ? " (v#{a["version"]})" : ""
+          "#{a["name"]}#{v}"
+        end
+
+        "Analyzers: #{names.join(", ")}"
+      end
+
+      def format_row(row, metadata)
+        analyzers = metadata["analyzers"] || []
+        timestamp = format_timestamp(row["packet_timestamp"])
+
+        if (reason = row["skipped_message_reason"])
+          return ["#{timestamp}  Skipped: #{reason}"]
+        end
+
+        events = row["events"] || []
+        present_events = events.each_with_index.reject { |e, _| e.nil? }
+
+        if present_events.empty?
+          return ["#{timestamp}  No events"]
+        end
+
+        present_events.map do |event, index|
+          event_type = event["event_type"] || "Unknown"
+          message = event["message"]
+          analyzer = analyzers.dig(index, "name")
+          analyzer_part = analyzer ? "(#{analyzer}) " : ""
+          "#{timestamp}  #{event_type.ljust(13)}  #{analyzer_part}#{message}"
+        end
+      end
+
+      def format_timestamp(ts)
+        return "[no timestamp]" unless ts
+        time = Time.parse(ts).utc
+        "[#{time.strftime("%Y-%m-%d %H:%M:%S UTC")}]"
+      rescue ArgumentError
+        "[#{ts}]"
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/analysis_report_json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Raygatherer
+  module Formatters
+    class AnalysisReportJSON
+      def format(data)
+        ::JSON.generate({"metadata" => data[:metadata], "rows" => data[:rows]})
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/recording_list_human.rb

@@ -59,13 +59,18 @@ module Raygatherer
 
         lines << "  Size:         #{format_size(entry["qmdl_size_bytes"])}"
 
+        if !active && entry["stop_reason"]
+          lines << "  Stop reason:  #{entry["stop_reason"]}"
+        end
+
         lines.join("\n")
       end
 
       def format_time(time_string)
         return "" unless time_string
-
         Time.parse(time_string).strftime("%Y-%m-%d %H:%M:%S")
+      rescue ArgumentError
+        time_string
       end
     end
   end

data/lib/raygatherer/formatters/time_human.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Raygatherer
+  module Formatters
+    class TimeHuman
+      def format(time)
+        lines = []
+        lines << "System time:   #{time["system_time"]}"
+        lines << "Adjusted time: #{time["adjusted_time"]}"
+        lines << "Offset:        #{time["offset_seconds"]}s"
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/raygatherer/formatters/time_json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Raygatherer
+  module Formatters
+    class TimeJSON
+      def format(time)
+        ::JSON.generate(time)
+      end
+    end
+  end
+end

data/lib/raygatherer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raygatherer
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/raygatherer.rb

@@ -4,16 +4,20 @@ require_relative "raygatherer/version"
 require_relative "raygatherer/config"
 require_relative "raygatherer/cli"
 require_relative "raygatherer/api_client"
-require_relative "raygatherer/formatters/human"
-require_relative "raygatherer/formatters/json"
+require_relative "raygatherer/formatters/alerts_human"
+require_relative "raygatherer/formatters/alerts_json"
 require_relative "raygatherer/formatters/recording_list_json"
 require_relative "raygatherer/formatters/recording_list_human"
 require_relative "raygatherer/formatters/stats_json"
 require_relative "raygatherer/formatters/stats_human"
 require_relative "raygatherer/formatters/analysis_status_json"
 require_relative "raygatherer/formatters/analysis_status_human"
+require_relative "raygatherer/formatters/analysis_report_json"
+require_relative "raygatherer/formatters/analysis_report_human"
 require_relative "raygatherer/formatters/config_json"
 require_relative "raygatherer/formatters/config_human"
+require_relative "raygatherer/formatters/time_json"
+require_relative "raygatherer/formatters/time_human"
 require_relative "raygatherer/spinner"
 require_relative "raygatherer/commands/base"
 require_relative "raygatherer/commands/alerts"
@@ -22,12 +26,17 @@ require_relative "raygatherer/commands/recording/download"
 require_relative "raygatherer/commands/recording/delete"
 require_relative "raygatherer/commands/recording/stop"
 require_relative "raygatherer/commands/recording/start"
+require_relative "raygatherer/commands/log"
 require_relative "raygatherer/commands/stats"
 require_relative "raygatherer/commands/analysis/status"
 require_relative "raygatherer/commands/analysis/run"
+require_relative "raygatherer/commands/analysis/report"
 require_relative "raygatherer/commands/config/show"
 require_relative "raygatherer/commands/config/set"
 require_relative "raygatherer/commands/config/test_notification"
+require_relative "raygatherer/commands/debug/display_state"
+require_relative "raygatherer/commands/time/show"
+require_relative "raygatherer/commands/time/sync"
 
 module Raygatherer
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raygatherer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mike Stallard
@@ -47,7 +47,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
-- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - Makefile
@@ -58,30 +57,39 @@ files:
 - lib/raygatherer/api_client.rb
 - lib/raygatherer/cli.rb
 - lib/raygatherer/commands/alerts.rb
+- lib/raygatherer/commands/analysis/report.rb
 - lib/raygatherer/commands/analysis/run.rb
 - lib/raygatherer/commands/analysis/status.rb
 - lib/raygatherer/commands/base.rb
 - lib/raygatherer/commands/config/set.rb
 - lib/raygatherer/commands/config/show.rb
 - lib/raygatherer/commands/config/test_notification.rb
+- lib/raygatherer/commands/debug/display_state.rb
+- lib/raygatherer/commands/log.rb
 - lib/raygatherer/commands/recording/delete.rb
 - lib/raygatherer/commands/recording/download.rb
 - lib/raygatherer/commands/recording/list.rb
 - lib/raygatherer/commands/recording/start.rb
 - lib/raygatherer/commands/recording/stop.rb
 - lib/raygatherer/commands/stats.rb
+- lib/raygatherer/commands/time/show.rb
+- lib/raygatherer/commands/time/sync.rb
 - lib/raygatherer/config.rb
 - lib/raygatherer/format_helpers.rb
+- lib/raygatherer/formatters/alerts_human.rb
+- lib/raygatherer/formatters/alerts_json.rb
+- lib/raygatherer/formatters/analysis_report_human.rb
+- lib/raygatherer/formatters/analysis_report_json.rb
 - lib/raygatherer/formatters/analysis_status_human.rb
 - lib/raygatherer/formatters/analysis_status_json.rb
 - lib/raygatherer/formatters/config_human.rb
 - lib/raygatherer/formatters/config_json.rb
-- lib/raygatherer/formatters/human.rb
-- lib/raygatherer/formatters/json.rb
 - lib/raygatherer/formatters/recording_list_human.rb
 - lib/raygatherer/formatters/recording_list_json.rb
 - lib/raygatherer/formatters/stats_human.rb
 - lib/raygatherer/formatters/stats_json.rb
+- lib/raygatherer/formatters/time_human.rb
+- lib/raygatherer/formatters/time_json.rb
 - lib/raygatherer/spinner.rb
 - lib/raygatherer/version.rb
 homepage: https://github.com/mjstallard/raygatherer
@@ -98,7 +106,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/CLAUDE.md

@@ -1,102 +0,0 @@
-# PROJECT OVERVIEW
-
-Raygatherer: Ruby CLI for fetching and displaying alerts from Rayhunter (cell tower / IMSI catcher analysis device). Ruby >= 3.1.0.
-
-# QUICK REFERENCE
-
-- Run tests: `bundle exec rspec`
-- Run CLI: `bundle exec ./exe/raygatherer`
-- CI: GitHub Actions on push to master and all PRs
-- `rayhunter` itself is checked out at `/Users/mike/workspace/rayhunter/`
-
-# ARCHITECTURE
-
-- Entry point: `exe/raygatherer` → `Raygatherer::CLI.run`
-- CLI routing: `lib/raygatherer/cli.rb`
-- Commands: `lib/raygatherer/commands/` (one class per subcommand)
-- API client: `lib/raygatherer/api_client.rb` (HTTP + NDJSON parsing)
-- Formatters: `lib/raygatherer/formatters/` (human and JSON, both accept arrays)
-- Tests mirror `lib/` structure under `spec/`, plus `spec/integration/` for CLI end-to-end tests
-
-# KEY CONVENTIONS
-
-- Formatters always receive and return arrays (even when empty)
-- JSON output is always a JSON array
-- Exit codes encode alert severity for scripting use (see `show_help` in status.rb)
-- Linter: `bundle exec standardrb` (Ruby Standard Style). Write new code in standardrb style to avoid rework.
-
-# ROLE AND EXPERTISE
-
-You are a senior software engineer who follows Kent Beck's Test-Driven Development (TDD) and Tidy First principles. Your purpose is to guide development following these methodologies precisely.
-
-# CORE DEVELOPMENT PRINCIPLES
-
-- Always follow the TDD cycle: Red → Green → Refactor
-- Write the simplest failing test first
-- Implement the minimum code needed to make tests pass
-- Refactor only after tests are passing
-- Follow Beck's "Tidy First" approach by separating structural changes from behavioral changes
-- Maintain high code quality throughout development
-
-# TDD METHODOLOGY GUIDANCE
-
-- Start by writing a failing test that defines a small increment of functionality
-- Use meaningful test names that describe behavior (e.g., "should sum two positive integers")
-- Make test failures clear and informative
-- Write just enough code to make the test pass - no more
-- Once tests pass, consider if refactoring is needed
-- Repeat the cycle for new functionality
-- When fixing a defect, first write an API-level failing test then write the smallest possible test that replicates the problem then get both tests to pass.
-
-# TIDY FIRST APPROACH
-
-- Separate all changes into two distinct types:
-  1. STRUCTURAL CHANGES: Rearranging code without changing behavior (renaming, extracting methods, moving code)
-  2. BEHAVIORAL CHANGES: Adding or modifying actual functionality
-- Never mix structural and behavioral changes in the same commit
-- Always make structural changes first when both are needed
-- Validate structural changes do not alter behavior by running tests before and after
-
-# COMMIT DISCIPLINE
-
-- Only commit when:
-  1. ALL tests are passing (`bundle exec rspec`)
-  2. ALL standardrb issues are resolved (`bundle exec standardrb`); fix any issues before committing
-  3. The change represents a single logical unit of work
-  4. Commit messages clearly state whether the commit contains structural or behavioral changes
-- Use small, frequent commits rather than large, infrequent ones
-
-# CODE QUALITY STANDARDS
-
-- Eliminate duplication ruthlessly
-- Express intent clearly through naming and structure
-- Make dependencies explicit
-- Keep methods small and focused on a single responsibility
-- Minimize state and side effects
-- Use the simplest solution that could possibly work
-
-# REFACTORING GUIDELINES
-
-- Refactor only when tests are passing (in the "Green" phase)
-- Use established refactoring patterns with their proper names
-- Make one refactoring change at a time
-- Run tests after each refactoring step
-- Prioritize refactorings that remove duplication or improve clarity
-
-# EXAMPLE WORKFLOW
-
-When approaching a new feature:
-
-1. Write a simple failing test for a small part of the feature
-2. Implement the bare minimum to make it pass
-3. Run tests to confirm they pass (Green)
-4. Run `bundle exec standardrb` and fix any issues
-5. Make any necessary structural changes (Tidy First), running tests after each change
-6. Commit structural changes separately
-7. Add another test for the next small increment of functionality
-8. Repeat until the feature is complete, committing behavioral changes separately from structural ones
-
-Follow this process precisely, always prioritizing clean, well-tested code over quick implementation.
-
-Always write one test at a time, make it run, then improve structure. Always run all the tests (except long-running tests) each time.
-