analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/cli/presenter.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "presenter_csv"
+
 module AnalyticsOps
   class CLI
     # Formats gem-owned values for terminal and automation consumers.
     class Presenter
+      include PresenterCSV
+
       OVERVIEW_LABELS = {
         "overview_totals" => "Totals",
         "overview_trend" => "Daily trend",
@@ -18,6 +22,11 @@ module AnalyticsOps
       end
 
       def render(value, status: CLI::SUCCESS)
+        if value.is_a?(Reports::ExportResult)
+          @format == "json" ? @out.write(json(value)) : @out.puts(human(value))
+          return status
+        end
+
         case @format
         when "json"
           @out.write(json(value))
@@ -41,6 +50,41 @@ module AnalyticsOps
         write(lines.join("\n"))
       end
 
+      def render_connections(connections)
+        return render(connections) unless @format == "human"
+        if connections.empty?
+          return write("No Google connections saved. Run `analytics-ops setup --service-account PATH`.")
+        end
+
+        lines = connections.map do |connection|
+          status = connection.fetch("available") ? "ready" : "key unavailable"
+          in_use = connection.fetch("in_use") ? " · in use" : ""
+          "#{display(connection.fetch("name"))}: #{status}#{in_use}"
+        end
+        write(lines.join("\n"))
+      end
+
+      def render_profiles(profiles)
+        return render(profiles) unless @format == "human"
+
+        lines = profiles.map do |profile|
+          marker = profile.fetch("selected") ? "*" : " "
+          connection = profile["connection"] || "not connected"
+          "#{marker} #{display(profile.fetch("name"))}: property #{display(profile.fetch("property_id"))} " \
+            "· connection #{display(connection)}"
+        end
+        write(lines.join("\n"))
+      end
+
+      def render_selection(selection)
+        return render(selection) unless @format == "human"
+
+        write(
+          "Using profile #{display(selection.fetch("profile"))} with connection " \
+          "#{display(selection.fetch("connection"))}."
+        )
+      end
+
       def json(value)
         payload = serializable(value)
         "#{JSON.pretty_generate(Canonical.normalize(payload))}\n"
@@ -64,16 +108,6 @@ module AnalyticsOps
 
       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)} " \
@@ -81,22 +115,9 @@ module AnalyticsOps
         ]
         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("\"", "\"\"")}\""
+        lines << "    before: #{complete_display(JSON.generate(Canonical.normalize(change.before)))}"
+        lines << "    after:  #{complete_display(JSON.generate(Canonical.normalize(change.after)))}"
+        lines << "    rollback: #{complete_display(change.rollback)}"
       end
 
       def serializable(value)
@@ -123,10 +144,46 @@ module AnalyticsOps
           "#{value.converged ? "Converged" : "Drift found"}: #{value.plan.changes.length} planned changes"
         when Applier::Result
           "Apply #{value.status}: #{value.applied.length} changes completed"
+        else
+          human_analytics_value(value)
+        end
+      end
+
+      def human_analytics_value(value)
+        case value
         when Reports::Result
           human_report(value)
         when Reports::OverviewResult
           human_overview(value)
+        when Reports::FieldList
+          human_fields(value)
+        when Reports::RecipeList
+          human_recipes(value)
+        when Reports::Compatibility
+          human_compatibility(value)
+        when Reports::ExportResult
+          "Exported #{value.rows} rows to #{complete_display(value.path)}"
+        else
+          human_operations_value(value)
+        end
+      end
+
+      def human_operations_value(value)
+        case value
+        when Health::Result
+          human_health(value)
+        when Governance::Result
+          human_governance(value)
+        when Governance::ChangeHistory
+          human_change_history(value)
+        when Governance::AccessReport
+          human_access_report(value)
+        when BigQuery::Result
+          human_bigquery(value)
+        when Portfolio::Result
+          human_portfolio(value)
+        when Portfolio::Collection
+          human_portfolio_collection(value)
         when Array
           human_discovery(value)
         else
@@ -134,6 +191,155 @@ module AnalyticsOps
         end
       end
 
+      def human_bigquery(value)
+        lines = [
+          "Experimental BigQuery report #{display(value.name)} — #{value.rows.length} rows · " \
+          "#{value.bytes_processed} bytes processed"
+        ]
+        return (lines << "No rows returned").join("\n") if value.rows.empty?
+
+        widths = value.headers.to_h do |header|
+          values = value.rows.map { |row| display(row.fetch(header)) }
+          [header, ([header.length] + values.map(&:length)).max.clamp(1, 60)]
+        end
+        lines << table_row(value.headers, widths)
+        lines << value.headers.map { |header| "-" * widths.fetch(header) }.join("-+-")
+        value.rows.each do |row|
+          lines << table_row(value.headers.map { |header| row.fetch(header) }, widths, headers: value.headers)
+        end
+        lines.join("\n")
+      end
+
+      def human_governance(result)
+        snapshot = result.snapshot
+        lines = [
+          "Experimental governance audit for property #{display(snapshot.property_id)}",
+          "#{snapshot.stream_settings.length} web streams · #{snapshot.channel_groups.length} channel groups · " \
+          "#{snapshot.calculated_metrics.length} calculated metrics · #{snapshot.bigquery_links.length} BigQuery links"
+        ]
+        if result.findings.empty?
+          lines << "OK       No configured governance mismatch found"
+        else
+          result.findings.each do |finding|
+            status = display(finding.severity).upcase.ljust(8)
+            lines << "#{status} #{display(finding.code)}: #{display(finding.message)}"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def human_change_history(value)
+        heading = "Experimental change history for property #{display(value.property_id)}"
+        lines = ["#{heading} — #{value.events.length} events"]
+        value.events.each do |event|
+          lines << "#{display(event["change_time"] || "unknown time")} · " \
+                   "#{display(event["actor_type"] || "unknown actor")} · #{Array(event["changes"]).length} changes"
+          Array(event["changes"]).each do |change|
+            lines << "  #{display(change.fetch("action")).upcase.ljust(10)} #{display(change.fetch("resource"))}"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def human_access_report(value)
+        value.dimension_headers
+        value.metric_headers
+        report = Reports::Result.new(
+          name: "access_report",
+          kind: "standard",
+          dimension_headers: value.dimension_headers,
+          metric_headers: value.metric_headers,
+          rows: value.rows,
+          row_count: value.row_count,
+          metadata: { "quota" => value.quota }
+        )
+        [
+          "Experimental aggregate Data API quota access for property #{display(value.property_id)}",
+          *human_report_table(report)
+        ]
+          .join("\n")
+      end
+
+      def human_portfolio_collection(collection)
+        lines = ["Portfolio #{display(collection.name)} — #{collection.entries.length} properties"]
+        collection.entries.each do |entry|
+          lines.concat(human_portfolio_entry(collection.kind, entry))
+        end
+        lines.join("\n")
+      end
+
+      def human_portfolio_entry(kind, entry)
+        identity = portfolio_identity(entry)
+        return ["ERROR    #{identity}: #{display(entry.error.fetch("message"))}"] if entry.status == "error"
+        return [human_portfolio_health_entry(identity, entry)] if kind == "health"
+
+        rows = entry.result.fetch("rows").length
+        ["OK       #{identity}: #{rows} returned rows"] +
+          portfolio_report_table(entry.result).map { |line| "  #{line}" }
+      end
+
+      def portfolio_identity(entry)
+        identity = "#{display(entry.profile)} (property #{display(entry.property_id)})"
+        labels = entry.labels.map { |name, value| "#{display(name)}=#{display(value)}" }.join(", ")
+        labels.empty? ? identity : "#{identity} · #{labels}"
+      end
+
+      def human_portfolio_health_entry(identity, entry)
+        status = entry.result.fetch("healthy") ? "OK" : "ISSUES"
+        findings = entry.result.fetch("findings").count { |finding| finding.fetch("severity") != "ok" }
+        "#{status.ljust(8)} #{identity}: #{findings} findings"
+      end
+
+      def portfolio_report_table(payload)
+        result = Reports::Result.new(
+          name: payload.fetch("name"),
+          kind: payload.fetch("kind"),
+          dimension_headers: payload.fetch("dimension_headers"),
+          metric_headers: payload.fetch("metric_headers"),
+          rows: payload.fetch("rows"),
+          row_count: payload.fetch("row_count"),
+          metadata: payload.fetch("metadata")
+        )
+        human_report_table(result)
+      end
+
+      def human_health(result)
+        current = result.summary.fetch("current")
+        lines = [
+          "Analytics health for #{display(result.profile)} / property #{display(result.property_id)}",
+          "Current: #{display(current.fetch("sessions"))} sessions · " \
+          "#{display(current.fetch("activeUsers"))} users · #{display(current.fetch("keyEvents"))} key events"
+        ]
+        result.findings.each do |finding|
+          lines << "#{display(finding.severity).upcase.ljust(8)} #{display(finding.code)}: #{display(finding.message)}"
+        end
+        lines.join("\n")
+      end
+
+      def human_fields(list)
+        return "No matching report fields found" if list.fields.empty?
+
+        list.fields.map do |field|
+          custom = field.custom_definition ? " · custom" : ""
+          name = display(field.ui_name || field.api_name)
+          "#{display(field.kind).ljust(9)} #{display(field.api_name)} — #{name}#{custom}"
+        end.join("\n")
+      end
+
+      def human_recipes(list)
+        list.recipes.map do |recipe|
+          "#{display(recipe.name).ljust(32)} #{display(recipe.kind).ljust(8)} #{display(recipe.source)}"
+        end.join("\n")
+      end
+
+      def human_compatibility(value)
+        lines = ["Report #{display(value.report_name)} is #{value.compatible ? "compatible" : "not compatible"}"]
+        (value.dimensions + value.metrics).each do |entry|
+          lines << "  #{display(entry.fetch("compatibility")).upcase.ljust(14)} #{display(entry.fetch("api_name"))}"
+        end
+        lines.join("\n")
+      end
+
       def human_doctor(value)
         value.checks.map do |check|
           status = display(check.fetch("status")).upcase.ljust(11)
@@ -149,7 +355,7 @@ module AnalyticsOps
       end
 
       def human_overview(overview)
-        lines = ["Overview for property #{display(overview.property_id)} — previous 28 complete days"]
+        lines = ["Overview for property #{display(overview.property_id)}"]
         overview.reports.each do |report|
           lines << ""
           lines << OVERVIEW_LABELS.fetch(report.name, report.name)
@@ -158,6 +364,22 @@ module AnalyticsOps
         lines.join("\n")
       end
 
+      def human_portfolio(portfolio)
+        headers = %w[profile property_id period active_users sessions key_events]
+        rows = portfolio.entries.map(&:to_h)
+        widths = headers.to_h do |header|
+          values = rows.map { |row| display(row.fetch(header)) }
+          [header, ([header.length] + values.map(&:length)).max.clamp(1, 60)]
+        end
+        lines = ["Portfolio overview — #{portfolio.entries.length} property/period rows"]
+        lines << table_row(headers, widths)
+        lines << headers.map { |header| "-" * widths.fetch(header) }.join("-+-")
+        rows.each do |row|
+          lines << table_row(headers.map { |header| row.fetch(header) }, widths, headers:)
+        end
+        lines.join("\n")
+      end
+
       def human_report_table(result)
         return ["No rows returned"] if result.rows.empty?
 
@@ -175,10 +397,19 @@ module AnalyticsOps
 
       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))
+          truncate_cell(complete_display(value), widths.fetch(header)).ljust(widths.fetch(header))
         end.join(" | ")
       end
 
+      def truncate_cell(value, width)
+        return value if value.length <= width
+        return "…" if width == 1
+
+        left = (width - 1) / 2
+        right = width - left - 1
+        "#{value.slice(0, left)}…#{value.slice(-right, right)}"
+      end
+
       def human_discovery(accounts)
         return "No accessible Google Analytics accounts found" if accounts.empty?
 
@@ -199,6 +430,10 @@ module AnalyticsOps
         Redaction.message(value)
       end
 
+      def complete_display(value)
+        Redaction.text(value)
+      end
+
       def safe_human_value(value)
         case value
         when Hash

data/lib/analytics_ops/cli/presenter_csv.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  class CLI
+    # CSV formatting isolated from the human and JSON presenter paths.
+    module PresenterCSV
+      private
+
+      def csv(value)
+        return portfolio_csv(value) if value.is_a?(Portfolio::Collection) && value.kind == "report"
+        return tabular_csv(value.headers, value.rows) if value.is_a?(BigQuery::Result)
+        unless value.is_a?(Reports::Result)
+          raise OptionParser::InvalidArgument, "CSV output is only valid for report results"
+        end
+
+        tabular_csv(value.headers, value.rows)
+      end
+
+      def tabular_csv(headers, rows)
+        lines = [headers.map { |header| csv_cell(header) }]
+        rows.each { |row| lines << headers.map { |header| csv_cell(row.fetch(header)) } }
+        encode_csv(lines)
+      end
+
+      def portfolio_csv(value)
+        successful = successful_portfolio_entries(value)
+        headers = shared_report_headers(successful)
+        label_names = successful.flat_map { |entry| entry.labels.keys }.uniq.sort
+        output_headers = portfolio_headers(headers, label_names)
+        lines = [output_headers.map { |header| csv_cell(header) }]
+        successful.each do |entry|
+          lines.concat(portfolio_entry_rows(entry, headers, label_names))
+        end
+        encode_csv(lines)
+      end
+
+      def successful_portfolio_entries(value)
+        unless value.success?
+          raise RemoteError, "Portfolio CSV requires every property to succeed; use JSON to inspect isolated failures"
+        end
+
+        value.entries.select { |entry| entry.status == "ok" }
+      end
+
+      def shared_report_headers(entries)
+        reports = entries.map(&:result)
+        headers = Array(reports.first&.fetch("dimension_headers", []))
+        headers += Array(reports.first&.fetch("metric_headers", []))
+        same = reports.all? do |report|
+          report.fetch("dimension_headers") + report.fetch("metric_headers") == headers
+        end
+        raise RemoteError, "Portfolio report headers differ across profiles" unless same
+
+        headers
+      end
+
+      def portfolio_headers(report_headers, label_names)
+        headers = %w[profile property_id] + label_names.map { |name| "label_#{name}" } + report_headers
+        unless headers.uniq.length == headers.length
+          raise RemoteError, "Portfolio CSV context columns conflict with report headers"
+        end
+
+        headers
+      end
+
+      def portfolio_entry_rows(entry, headers, label_names)
+        labels = label_names.map { |name| entry.labels.fetch(name, "") }
+        entry.result.fetch("rows").map do |row|
+          values = [entry.profile, entry.property_id] + labels + headers.map { |header| row.fetch(header) }
+          values.map { |value| csv_cell(value) }
+        end
+      end
+
+      def encode_csv(lines)
+        "#{lines.map { |line| line.map { |cell| csv_field(cell) }.join(",") }.join("\n")}\n"
+      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
+    end
+  end
+end

data/lib/analytics_ops/cli/reporting_commands.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Command-line consumer of the public Analytics Ops API.
+  class CLI
+    # Implements date-aware reporting and multi-property portfolio commands.
+    module ReportingCommands
+      private
+
+      def run_portfolio
+        portfolio = @portfolio_loader.call(
+          config: @options.fetch(:config),
+          store: service_account_store,
+          workspace_loader: @workspace_loader,
+          service_account_loader: @service_account_loader,
+          transport: @options.fetch(:transport),
+          timeout: @options[:timeout],
+          logger: operation_logger
+        )
+        ranges = report_date_ranges
+        concurrency = @options.fetch(:concurrency, 4)
+        case @arguments
+        when []
+          result = ranges ? portfolio.overview(date_ranges: ranges) : portfolio.overview
+          render(result)
+        when ["health"]
+          health_ranges = ranges && ensure_comparison(ranges)
+          result = if health_ranges
+                     portfolio.health(date_ranges: health_ranges, concurrency:)
+                   else
+                     portfolio.health(concurrency:)
+                   end
+          render(result, status: result.success? ? SUCCESS : DRIFT)
+        else
+          unless @arguments.length == 2 && @arguments.first == "report"
+            raise OptionParser::InvalidArgument, "portfolio accepts no arguments, `health`, or `report NAME`"
+          end
+
+          result = portfolio.report(@arguments.last, date_ranges: ranges, concurrency:)
+          render(result, status: result.success? ? SUCCESS : REMOTE_ERROR)
+        end
+      end
+
+      def render_workspace_overview(workspace)
+        ranges = report_date_ranges
+        render(ranges ? workspace.overview(date_ranges: ranges) : workspace.overview)
+      end
+
+      def render_workspace_report(workspace)
+        name = required_report_name!("report")
+        ranges = report_date_ranges
+        definition = name == "custom" ? @options.fetch(:custom_definition) : name
+        if @options.fetch(:all_rows)
+          return render(
+            workspace.export_report(
+              definition,
+              path: @options.fetch(:output),
+              date_ranges: ranges,
+              page_size: @options.fetch(:page_size, Workspace::DEFAULT_PAGE_SIZE),
+              max_rows: @options.fetch(:max_rows, Workspace::MAX_EXPORT_ROWS)
+            )
+          )
+        end
+
+        render(ranges ? workspace.report(definition, date_ranges: ranges) : workspace.report(definition))
+      end
+
+      def render_workspace_fields(workspace)
+        raise OptionParser::InvalidArgument, "fields accepts at most one SEARCH term" if @arguments.length > 1
+
+        render(workspace.report_metadata(query: @arguments.first, kind: @options[:field_kind]))
+      end
+
+      def render_workspace_compatibility(workspace)
+        name = required_report_name!("compatibility")
+        render(workspace.report_compatibility(name))
+      end
+
+      def render_workspace_health(workspace)
+        ranges = report_date_ranges
+        result = ranges ? workspace.health(date_ranges: ensure_comparison(ranges)) : workspace.health
+        render(result, status: result.healthy? ? SUCCESS : DRIFT)
+      end
+
+      def render_workspace_raw_report(workspace)
+        name = required_report_name!("raw")
+        ranges = report_date_ranges
+        render(
+          workspace.raw_report(
+            name,
+            date_ranges: ranges,
+            limit: @options.fetch(:limit, 1_000)
+          )
+        )
+      end
+
+      def render_workspace_funnel(workspace)
+        name = required_report_name!("funnel")
+        ranges = report_date_ranges
+        render(workspace.funnel(name, date_ranges: ranges))
+      end
+
+      def ensure_comparison(ranges)
+        return ranges if ranges.length == 2
+
+        selected = ranges.fetch(0)
+        Reports::Period.resolve(
+          start_date: selected.fetch("start_date"),
+          end_date: selected.fetch("end_date"),
+          compare: true
+        )
+      rescue InvalidRequestError
+        days = @options[:last_days] || Reports::Period::DEFAULT_DAYS
+        Reports::Period.resolve(last_days: days, compare: true)
+      end
+
+      def report_date_ranges
+        Reports::Period.resolve(
+          last_days: @options[:last_days],
+          start_date: @options[:start_date],
+          end_date: @options[:end_date],
+          compare: @options.fetch(:compare)
+        )
+      end
+    end
+
+    include ReportingCommands
+  end
+end

data/lib/analytics_ops/cli/setup_commands.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  # Command-line consumer of the public Analytics Ops API.
+  class CLI
+    # Implements safe, interactive and non-interactive Google setup.
+    module SetupCommands
+      private
+
+      def setup(connection, service_account, profile:)
+        result = run_setup(connection, service_account, profile:)
+        connection_name = remember_setup_connection(profile, service_account)
+        return render_setup_result(result, connection_name) if human?
+
+        render(result.to_h.merge("connection" => connection_name))
+      end
+
+      def run_setup(connection, service_account, profile:)
+        Setup.new(
+          connection:,
+          config: @options.fetch(:config),
+          profile:,
+          property_id: @options[:property],
+          noninteractive: @options[:noninteractive],
+          warnings: service_account_warnings(service_account),
+          input: @input,
+          out: @out
+        ).call
+      end
+
+      def remember_setup_connection(profile, service_account)
+        connection_name = setup_connection_name(profile, service_account)
+        service_account_store.write(
+          service_account.path,
+          name: connection_name,
+          config: @options.fetch(:config),
+          profile:
+        )
+        connection_name
+      end
+
+      def render_setup_result(result, connection_name)
+        action = if result.created?
+                   "Created"
+                 elsif result.updated?
+                   "Updated"
+                 else
+                   "Using"
+                 end
+        @out.puts "#{action} #{Redaction.message(result.config_path)}"
+        @out.puts "Connected #{Redaction.message(result.profile)} to " \
+                  "#{Redaction.message(result.property.display_name)} " \
+                  "(property #{Redaction.message(result.property.id)})."
+        @out.puts "Saved Google connection #{Redaction.message(connection_name)}."
+        result.warnings.each { |warning| @err.puts "Warning: #{Redaction.message(warning)}" }
+        @out.puts "Next: analytics-ops overview"
+        SUCCESS
+      end
+
+      def setup_connection_name(profile, service_account)
+        return @options.fetch(:connection) if @options[:connection]
+        return new_connection_name(profile, service_account) if @options[:service_account]
+        return profile unless service_account_store.respond_to?(:resolve_connection_name)
+
+        service_account_store.resolve_connection_name(
+          config: @options.fetch(:config),
+          profile:
+        )
+      end
+
+      def new_connection_name(profile, service_account)
+        return profile unless service_account_store.respond_to?(:connection_name_for)
+
+        service_account_store.connection_name_for(
+          service_account.path,
+          preferred: profile,
+          config: @options.fetch(:config),
+          profile:
+        )
+      end
+
+      def service_account_warnings(service_account)
+        return [] unless service_account.respond_to?(:security_warnings)
+
+        service_account.security_warnings
+      end
+    end
+
+    include SetupCommands
+  end
+end