analytics_ops 0.1.0 → 0.2.0

data/lib/analytics_ops/cli/options.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  class CLI
+    # Parses and validates command-line options without loading a workspace.
+    class Options
+      DEFAULTS = {
+        config: "config/analytics_ops.yml",
+        profile: "production",
+        format: "human",
+        log_level: "warn",
+        transport: :grpc,
+        yes: false,
+        noninteractive: false
+      }.freeze
+      SETUP_OPTIONS = %i[property service_account].freeze
+      PROPERTY_ID = /\A\d{1,50}\z/
+      PROFILE = /\A[A-Za-z][A-Za-z0-9_]{0,63}\z/
+
+      attr_reader :values
+
+      def initialize(arguments)
+        @arguments = arguments
+        @values = DEFAULTS.dup
+        @explicit_format = nil
+      end
+
+      def parse!(command)
+        parser.parse!(@arguments)
+        validate!(command)
+        @values.freeze
+      end
+
+      private
+
+      def parser
+        OptionParser.new do |options|
+          add_file_options(options)
+          add_format_options(options)
+          add_setup_options(options)
+          add_client_options(options)
+          add_execution_options(options)
+        end
+      end
+
+      def add_file_options(options)
+        options.on("-c", "--config PATH", "Configuration path") { |path| @values[:config] = path }
+        options.on("-p", "--profile NAME", "Configuration profile") { |name| @values[:profile] = name }
+        options.on("-o", "--output PATH", "Write a generated plan to PATH") { |path| @values[:output] = path }
+      end
+
+      def add_format_options(options)
+        options.on("-f", "--format FORMAT", CLI::FORMATS, CLI::FORMATS.join(", ")) do |format|
+          select_format(format)
+        end
+        options.on("--json", "Use JSON output") { select_format("json") }
+        options.on("--csv", "Use CSV report output") { select_format("csv") }
+      end
+
+      def select_format(format)
+        if @explicit_format && @explicit_format != format
+          raise OptionParser::InvalidArgument, "choose exactly one output format"
+        end
+
+        @explicit_format = format
+        @values[:format] = format
+      end
+
+      def add_setup_options(options)
+        options.on("--property ID", "Property to select during setup") { |id| @values[:property] = id }
+        options.on("--service-account PATH", "Google service-account JSON key for setup") do |path|
+          @values[:service_account] = path
+        end
+      end
+
+      def add_client_options(options)
+        options.on("--log-level LEVEL", CLI::LOG_LEVELS, CLI::LOG_LEVELS.join(", ")) do |level|
+          @values[:log_level] = level
+        end
+        options.on("--transport TRANSPORT", %w[grpc rest], "grpc or rest") do |transport|
+          @values[:transport] = transport.to_sym
+        end
+        options.on("--timeout SECONDS", Float, "Google API timeout") do |seconds|
+          unless seconds.finite? && seconds.positive?
+            raise OptionParser::InvalidArgument, "timeout must be finite and positive"
+          end
+
+          @values[:timeout] = seconds
+        end
+      end
+
+      def add_execution_options(options)
+        options.on("--yes", "Approve every operation in a saved plan") { @values[:yes] = true }
+        options.on("--non-interactive", "Never prompt") { @values[:noninteractive] = true }
+      end
+
+      def validate!(command)
+        validate_arguments!(command)
+        validate_scoped_options!(command)
+        validate_setup! if command == "setup"
+        validate_format!(command)
+      end
+
+      def validate_arguments!(command)
+        return unless CLI::NO_ARGUMENT_COMMANDS.include?(command) && @arguments.any?
+
+        raise OptionParser::InvalidArgument, "#{command} does not accept positional arguments"
+      end
+
+      def validate_scoped_options!(command)
+        raise OptionParser::InvalidArgument, "--output is only valid with plan" if @values[:output] && command != "plan"
+        raise OptionParser::InvalidArgument, "--yes is only valid with apply" if @values[:yes] && command != "apply"
+        if @values[:noninteractive] && !%w[apply setup].include?(command)
+          raise OptionParser::InvalidArgument, "--non-interactive is only valid with apply or setup"
+        end
+        return if SETUP_OPTIONS.none? { |name| @values[name] } || command == "setup"
+
+        raise OptionParser::InvalidArgument, "--property and --service-account are setup-only"
+      end
+
+      def validate_setup!
+        validate_setup_property!
+        raise OptionParser::InvalidArgument, "--profile is invalid" unless PROFILE.match?(@values.fetch(:profile))
+
+        validate_service_account!
+        validate_setup_json!
+      end
+
+      def validate_setup_property!
+        if @values[:noninteractive] && !@values[:property]
+          raise OptionParser::MissingArgument, "Non-interactive setup requires --property ID"
+        end
+        return unless @values[:property] && !PROPERTY_ID.match?(@values.fetch(:property))
+
+        raise OptionParser::InvalidArgument, "--property must be a numeric GA4 property ID"
+      end
+
+      def validate_service_account!
+        return unless @values[:service_account] && !File.file?(@values.fetch(:service_account))
+
+        raise OptionParser::InvalidArgument, "--service-account must identify an existing file"
+      end
+
+      def validate_setup_json!
+        return unless @values.fetch(:format) == "json" && (!@values[:noninteractive] || !@values[:property])
+
+        raise OptionParser::MissingArgument, "JSON setup requires --non-interactive --property ID"
+      end
+
+      def validate_format!(command)
+        return unless @values.fetch(:format) == "csv" && !%w[report realtime].include?(command)
+
+        raise OptionParser::InvalidArgument, "CSV output is only valid for report results"
+      end
+    end
+  end
+end

data/lib/analytics_ops/cli/presenter.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  class CLI
+    # Formats gem-owned values for terminal and automation consumers.
+    class Presenter
+      OVERVIEW_LABELS = {
+        "overview_totals" => "Totals",
+        "overview_trend" => "Daily trend",
+        "overview_acquisition" => "Traffic acquisition",
+        "overview_landing_pages" => "Landing pages",
+        "overview_devices" => "Devices"
+      }.freeze
+
+      def initialize(out:, format:)
+        @out = out
+        @format = format
+      end
+
+      def render(value, status: CLI::SUCCESS)
+        case @format
+        when "json"
+          @out.write(json(value))
+        when "csv"
+          @out.write(csv(value))
+        else
+          @out.puts(human(value))
+        end
+        status
+      end
+
+      def render_properties(accounts)
+        return render(accounts) unless @format == "human"
+        return write("No accessible Google Analytics properties found") if accounts.empty?
+
+        lines = accounts.flat_map do |account|
+          ["Account #{display(account.id)}: #{display(account.display_name)}"] + account.properties.map do |property|
+            "  Property #{display(property.fetch("id"))}: #{display(property.fetch("display_name"))}"
+          end
+        end
+        write(lines.join("\n"))
+      end
+
+      def json(value)
+        payload = serializable(value)
+        "#{JSON.pretty_generate(Canonical.normalize(payload))}\n"
+      end
+
+      def human_plan(plan, detailed: false)
+        lines = [
+          "Plan for profile #{display(plan.profile)} / property #{display(plan.property_id)}",
+          "Snapshot: #{display(plan.snapshot_fingerprint)}",
+          "Changes: #{plan.changes.length}; findings: #{plan.findings.length}"
+        ]
+        plan.changes.each do |change|
+          lines.concat(human_plan_change(change, detailed:))
+        end
+        plan.findings.each do |finding|
+          lines << "  #{display(finding.severity).upcase.ljust(12)} #{display(finding.resource_identity)}: " \
+                   "#{display(finding.message)}"
+        end
+        lines.join("\n")
+      end
+
+      private
+
+      def csv(value)
+        unless value.is_a?(Reports::Result)
+          raise OptionParser::InvalidArgument, "CSV output is only valid for report results"
+        end
+
+        lines = [value.headers.map { |header| csv_cell(header) }]
+        value.rows.each { |row| lines << value.headers.map { |header| csv_cell(row.fetch(header)) } }
+        "#{lines.map { |line| line.map { |cell| csv_field(cell) }.join(",") }.join("\n")}\n"
+      end
+
+      def human_plan_change(change, detailed:)
+        lines = [
+          "  #{display(change.operation).upcase.ljust(6)} #{display(change.resource_type)} " \
+          "#{display(change.resource_identity)}"
+        ]
+        return lines unless detailed
+
+        lines << "    before: #{display(JSON.generate(Canonical.normalize(change.before)))}"
+        lines << "    after:  #{display(JSON.generate(Canonical.normalize(change.after)))}"
+        lines << "    rollback: #{display(change.rollback)}"
+      end
+
+      def csv_cell(value)
+        string = value.to_s.gsub(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/, "?")
+        dangerous = string.match?(/\A(?:[\p{Space}\uFEFF]*[=+\-@]|[\t\r\n])/)
+        dangerous ? "'#{string}" : string
+      end
+
+      def csv_field(value)
+        string = value.to_s
+        return string unless string.match?(/[",\r\n]/)
+
+        "\"#{string.gsub("\"", "\"\"")}\""
+      end
+
+      def serializable(value)
+        case value
+        when Array
+          value.map { |item| serializable(item) }
+        when Hash
+          value.to_h { |key, item| [key.to_s, serializable(item)] }
+        else
+          value.respond_to?(:to_h) ? serializable(value.to_h) : value
+        end
+      end
+
+      def human(value)
+        case value
+        when Plan
+          human_plan(value)
+        when Snapshot
+          "Snapshot #{display(value.fingerprint)}\n" \
+          "#{JSON.pretty_generate(Canonical.normalize(safe_human_value(value.to_h)))}"
+        when Workspace::DoctorResult
+          human_doctor(value)
+        when Workspace::Verification
+          "#{value.converged ? "Converged" : "Drift found"}: #{value.plan.changes.length} planned changes"
+        when Applier::Result
+          "Apply #{value.status}: #{value.applied.length} changes completed"
+        when Reports::Result
+          human_report(value)
+        when Reports::OverviewResult
+          human_overview(value)
+        when Array
+          human_discovery(value)
+        else
+          JSON.pretty_generate(Canonical.normalize(serializable(value)))
+        end
+      end
+
+      def human_doctor(value)
+        value.checks.map do |check|
+          status = display(check.fetch("status")).upcase.ljust(11)
+          "#{status} #{display(check.fetch("name"))}: #{display(check.fetch("detail"))}"
+        end.join("\n")
+      end
+
+      def human_report(result)
+        [
+          "Report #{display(result.name)} (#{display(result.kind)}) — #{result.row_count} rows",
+          *human_report_table(result)
+        ].join("\n")
+      end
+
+      def human_overview(overview)
+        lines = ["Overview for property #{display(overview.property_id)} — previous 28 complete days"]
+        overview.reports.each do |report|
+          lines << ""
+          lines << OVERVIEW_LABELS.fetch(report.name, report.name)
+          lines.concat(human_report_table(report))
+        end
+        lines.join("\n")
+      end
+
+      def human_report_table(result)
+        return ["No rows returned"] if result.rows.empty?
+
+        widths = result.headers.to_h do |header|
+          values = result.rows.map { |row| display(row.fetch(header)) }
+          [header, ([display(header).length] + values.map(&:length)).max.clamp(1, 60)]
+        end
+        lines = [table_row(result.headers, widths)]
+        lines << result.headers.map { |header| "-" * widths.fetch(header) }.join("-+-")
+        result.rows.each do |row|
+          lines << table_row(result.headers.map { |header| row.fetch(header) }, widths, headers: result.headers)
+        end
+        lines
+      end
+
+      def table_row(values, widths, headers: values)
+        values.zip(headers).map do |value, header|
+          display(value).slice(0, widths.fetch(header)).ljust(widths.fetch(header))
+        end.join(" | ")
+      end
+
+      def human_discovery(accounts)
+        return "No accessible Google Analytics accounts found" if accounts.empty?
+
+        accounts.flat_map do |account|
+          lines = ["Account #{display(account.id)}: #{display(account.display_name)}"]
+          account.properties.each do |property|
+            lines << "  Property #{display(property.fetch("id"))}: #{display(property.fetch("display_name"))}"
+            property.fetch("streams").each do |stream|
+              lines << "    Stream #{display(stream.fetch("id"))}: #{display(stream.fetch("display_name"))} " \
+                       "(#{display(stream.fetch("type"))})"
+            end
+          end
+          lines
+        end.join("\n")
+      end
+
+      def display(value)
+        Redaction.message(value)
+      end
+
+      def safe_human_value(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [key, safe_human_value(child)] }
+        when Array
+          value.map { |child| safe_human_value(child) }
+        when String
+          display(value)
+        else
+          value
+        end
+      end
+
+      def write(message)
+        @out.puts message
+        CLI::SUCCESS
+      end
+    end
+  end
+end