analytics_ops 0.2.0 → 0.3.0

data/lib/analytics_ops/cli.rb

@@ -23,15 +23,24 @@ module AnalyticsOps
     INTERRUPTED = 130
 
     COMMANDS = %w[
-      setup properties doctor discover snapshot audit plan apply verify overview report realtime schema
+      setup connections profiles use properties doctor discover snapshot audit plan apply verify overview report
+      realtime portfolio fields reports compatibility health governance changes access raw funnel schema mcp
     ].freeze
     FORMATS = %w[human json csv].freeze
     LOG_LEVELS = %w[debug info warn error].freeze
-    NO_ARGUMENT_COMMANDS = %w[setup properties doctor discover snapshot audit plan verify overview schema].freeze
+    NO_ARGUMENT_COMMANDS = %w[
+      setup connections profiles properties doctor discover snapshot audit plan verify overview health governance
+      changes access schema mcp
+      reports
+    ].freeze
     CONNECTION_COMMANDS = %w[setup properties discover].freeze
+    LOCAL_COMMANDS = %w[connections profiles use mcp].freeze
+    CORE_WORKSPACE_COMMANDS = %w[doctor snapshot audit plan apply verify].freeze
+    REPORTING_COMMANDS = %w[overview report realtime fields reports compatibility health].freeze
 
     def self.start(arguments, out: $stdout, err: $stderr, input: $stdin, workspace_loader: nil,
-                   connection_loader: nil, service_account_loader: nil, service_account_store: nil)
+                   connection_loader: nil, service_account_loader: nil, service_account_store: nil,
+                   mcp_server_loader: nil, portfolio_loader: nil)
       new(
         arguments,
         out:,
@@ -40,12 +49,14 @@ module AnalyticsOps
         workspace_loader:,
         connection_loader:,
         service_account_loader:,
-        service_account_store:
+        service_account_store:,
+        mcp_server_loader:,
+        portfolio_loader:
       ).call
     end
 
     def initialize(arguments, out:, err:, input:, workspace_loader:, connection_loader:,
-                   service_account_loader:, service_account_store:)
+                   service_account_loader:, service_account_store:, mcp_server_loader:, portfolio_loader:)
       @arguments = arguments.dup
       @json_requested = json_option_present?(@arguments)
       @out = out
@@ -55,6 +66,8 @@ module AnalyticsOps
       @connection_loader = connection_loader || method(:load_connection)
       @service_account_loader = service_account_loader || ServiceAccount.method(:load)
       @service_account_store = service_account_store
+      @mcp_server_loader = mcp_server_loader || method(:load_mcp_server)
+      @portfolio_loader = portfolio_loader || method(:load_portfolio)
     end
 
     def call
@@ -86,22 +99,25 @@ module AnalyticsOps
 
     def execute(command)
       return render(Configuration::SCHEMA, status: SUCCESS) if command == "schema"
+      return dispatch_local(command) if LOCAL_COMMANDS.include?(command)
+      return run_portfolio if command == "portfolio"
 
+      profile = resolved_profile
       if CONNECTION_COMMANDS.include?(command)
-        service_account = load_service_account
+        service_account = load_service_account(profile:)
         connection = @connection_loader.call(
           service_account:,
           transport: @options.fetch(:transport),
           timeout: @options[:timeout],
           logger: operation_logger
         )
-        return dispatch_connection(command, connection, service_account)
+        return dispatch_connection(command, connection, service_account, profile:)
       end
 
-      service_account = load_service_account
+      service_account = load_service_account(profile:)
       workspace = @workspace_loader.call(
         config: @options.fetch(:config),
-        profile: @options.fetch(:profile),
+        profile:,
         service_account:,
         transport: @options.fetch(:transport),
         timeout: @options[:timeout],
@@ -137,6 +153,13 @@ module AnalyticsOps
     end
 
     def dispatch(command, workspace)
+      return dispatch_core(command, workspace) if CORE_WORKSPACE_COMMANDS.include?(command)
+      return dispatch_reporting(command, workspace) if REPORTING_COMMANDS.include?(command)
+
+      dispatch_experimental(command, workspace)
+    end
+
+    def dispatch_core(command, workspace)
       case command
       when "doctor"
         result = workspace.doctor
@@ -153,48 +176,52 @@ module AnalyticsOps
       when "verify"
         verification = workspace.verify
         render(verification, status: verification.converged ? SUCCESS : DRIFT)
+      end
+    end
+
+    def dispatch_reporting(command, workspace)
+      case command
       when "overview"
-        render(workspace.overview)
+        render_workspace_overview(workspace)
       when "report"
-        render(workspace.report(required_report_name!("report")))
+        render_workspace_report(workspace)
       when "realtime"
         render(workspace.realtime(optional_realtime_name!))
+      when "fields"
+        render_workspace_fields(workspace)
+      when "reports"
+        render(workspace.report_recipes)
+      when "compatibility"
+        render_workspace_compatibility(workspace)
+      when "health"
+        render_workspace_health(workspace)
+      end
+    end
+
+    def dispatch_experimental(command, workspace)
+      case command
+      when "governance"
+        result = workspace.governance
+        render(result, status: result.compliant? ? SUCCESS : DRIFT)
+      when "changes"
+        render(workspace.change_history)
+      when "access"
+        render(workspace.access_report)
+      when "raw"
+        render_workspace_raw_report(workspace)
+      when "funnel"
+        render_workspace_funnel(workspace)
       end
     end
 
-    def dispatch_connection(command, connection, service_account)
+    def dispatch_connection(command, connection, service_account, profile:)
       case command
       when "discover"
         render(connection.discover)
       when "properties"
         render_properties(connection.properties)
       when "setup"
-        setup(connection, service_account)
-      end
-    end
-
-    def setup(connection, service_account)
-      result = Setup.new(
-        connection:,
-        config: @options.fetch(:config),
-        profile: @options.fetch(:profile),
-        property_id: @options[:property],
-        noninteractive: @options[:noninteractive],
-        input: @input,
-        out: @out
-      ).call
-      service_account_store.write(service_account.path)
-
-      if human?
-        action = result.created? ? "Created" : "Using"
-        @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 "Next: analytics-ops overview"
-        SUCCESS
-      else
-        render(result)
+        setup(connection, service_account, profile:)
       end
     end
 
@@ -248,13 +275,31 @@ module AnalyticsOps
       Connection.new(service_account:, transport:, timeout:, logger:)
     end
 
-    def load_service_account
+    def load_mcp_server(**)
+      require_relative "mcp_server"
+      MCPServer.new(**)
+    end
+
+    def load_portfolio(**)
+      Portfolio.new(**)
+    end
+
+    def load_service_account(profile:)
       @service_account_loader.call(
         path: @options[:service_account],
-        store: service_account_store
+        store: service_account_store,
+        connection: @options[:connection],
+        config: @options.fetch(:config),
+        profile:
       )
     end
 
+    def resolved_profile
+      return @options.fetch(:profile) if @options.fetch(:profile_explicit)
+
+      service_account_store.selected_profile(config: @options.fetch(:config)) || @options.fetch(:profile)
+    end
+
     def service_account_store
       @service_account_store ||= ServiceAccount::Store.new
     end
@@ -355,7 +400,11 @@ module AnalyticsOps
         Start here:
           setup        Connect Google, choose a property, and create configuration
           overview     Show a useful five-section summary for the selected property
+          portfolio    Compare totals, reports, or health across configured properties
           properties   List accessible accounts and properties without configuration
+          profiles     List saved property profiles
+          use NAME     Select a profile and its Google connection
+          connections  List saved Google connections
 
         Read-only commands:
           doctor       Validate local setup and Google API/property access
@@ -364,9 +413,20 @@ module AnalyticsOps
           audit        Compare desired and remote state (exit 2 for drift)
           plan         Generate a deterministic plan; use --output to save it
           verify       Prove whether managed state converges
-          report NAME  Run a built-in standard report
+          report NAME  Run a built-in, saved, or one-off custom standard report
+          reports      List built-in and saved report recipes
+          fields       Search property-aware dimensions and metrics
+          compatibility NAME
+                       Check whether a report's fields work together
+          health       Check traffic, events, data quality, quota, and config drift
+          governance   Audit broader GA4 settings (experimental, read-only)
+          changes      Read recent GA4 change history (experimental; edit scope)
+          access       Read aggregate Data API quota access (experimental)
+          raw NAME     Run an optional, cost-capped BigQuery recipe (experimental)
+          funnel NAME  Run a configured, aggregate user journey (experimental)
           realtime     Run realtime_events (or pass another realtime recipe)
           schema       Print the version-1 configuration schema
+          mcp          Start the strictly read-only AI connection
 
         Mutation command:
           apply FILE   Apply only a saved, non-stale plan; prompts unless --yes
@@ -377,11 +437,25 @@ module AnalyticsOps
 
         Common options:
           -c, --config PATH          Default: config/analytics_ops.yml
-          -p, --profile NAME        Default: production
-          -f, --format FORMAT       human, json, or report-only csv
+          -p, --profile NAME        Override the selected profile
+              --connection NAME     Override the profile's saved Google connection
+          -f, --format FORMAT       human, json, or result-only csv
               --json                Shortcut for --format json
               --csv                 Shortcut for --format csv
-          -o, --output PATH         Save a generated plan (plan only)
+              --last DAYS           Use the previous number of complete days
+              --from DATE           Report start date (use with --to)
+              --to DATE             Report end date (use with --from)
+              --compare             Include the equally long preceding period
+          -o, --output PATH         Save a plan, or a bounded --all CSV report
+              --dimension NAME      Repeatable field for report custom
+              --metric NAME         Repeatable field for report custom
+              --where FIELD=VALUE   Repeatable exact filter for report custom
+              --limit ROWS          Row limit for report custom or raw
+              --all                 Stream bounded report pages to --output
+              --max-rows ROWS       Hard limit for --all (max 1000000)
+              --page-size ROWS      Rows per --all request (max 250000)
+              --kind KIND           dimension or metric for fields
+              --concurrency COUNT   Portfolio workers (1-8)
               --property ID         Select a property without prompting (setup only)
               --service-account PATH Google service-account JSON key (setup only)
               --transport NAME      grpc or rest
@@ -396,3 +470,6 @@ end
 
 require_relative "cli/presenter"
 require_relative "cli/options"
+require_relative "cli/local_commands"
+require_relative "cli/reporting_commands"
+require_relative "cli/setup_commands"

data/lib/analytics_ops/clients/admin.rb

@@ -3,12 +3,19 @@
 # Official Admin API boundary.
 
 require_relative "admin_normalization"
+require_relative "admin_resource_normalization"
+require_relative "admin_governance_normalization"
+require_relative "admin_governance"
+require "time"
 
 module AnalyticsOps
   module Clients
     # Narrow adapter around Google's generated Admin client.
     class Admin
       include AdminNormalization
+      include AdminResourceNormalization
+      include AdminGovernanceNormalization
+      include AdminGovernance
 
       PACKAGE_REQUIREMENT = Gem::Requirement.new("~> 0.8.0")
       RETENTION_TO_GOOGLE = {
@@ -30,7 +37,18 @@ module AnalyticsOps
         "data_retention" => :update_data_retention_settings,
         "key_events" => :create_key_event,
         "custom_dimensions" => :create_custom_dimension,
-        "custom_metrics" => :create_custom_metric
+        "custom_metrics" => :create_custom_metric,
+        "enhanced_measurement_audit" => :get_enhanced_measurement_settings,
+        "data_redaction_audit" => :get_data_redaction_settings,
+        "reporting_identity_audit" => :get_reporting_identity_settings,
+        "attribution_audit" => :get_attribution_settings,
+        "channel_group_audit" => :list_channel_groups,
+        "calculated_metric_audit" => :list_calculated_metrics,
+        "event_create_rule_audit" => :list_event_create_rules,
+        "event_edit_rule_audit" => :list_event_edit_rules,
+        "bigquery_link_audit" => :list_big_query_links,
+        "change_history" => :search_change_history_events,
+        "access_report" => :run_access_report
       }.freeze
 
       def initialize(client: nil, service_account: nil, access: :read, transport: :grpc, timeout: nil, logger: nil)
@@ -176,6 +194,13 @@ module AnalyticsOps
         translate_errors { response.respond_to?(:to_a) ? response.to_a : Array(response) }
       end
 
+      def list_first(method_name, request, limit)
+        response = invoke(method_name, request)
+        translate_errors do
+          response.respond_to?(:first) ? response.first(limit) : Array(response).first(limit)
+        end
+      end
+
       def get(method_name, request)
         invoke(method_name, request)
       end
@@ -197,7 +222,8 @@ module AnalyticsOps
       end
 
       def request_resource(request)
-        request[:name] || request[:parent] || request.dig(:data_stream, :name) ||
+        request[:name] || request[:parent] || request[:property] || request[:entity] ||
+          request.dig(:data_stream, :name) ||
           request.dig(:data_retention_settings, :name)
       end
 

data/lib/analytics_ops/clients/admin_governance.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Clients
+    # Experimental read-only Admin API governance operations.
+    module AdminGovernance
+      def governance_snapshot(property_id)
+        property = property_name(property_id)
+        streams = list_streams(property_id).select { |stream| stream.type == "web" }.sort_by(&:id)
+        Governance::Snapshot.new(
+          property_id:,
+          stream_settings: governance_stream_settings(streams),
+          reporting_identity: resource_hash(
+            get(:get_reporting_identity_settings, name: "#{property}/reportingIdentitySettings")
+          ),
+          attribution: resource_hash(get(:get_attribution_settings, name: "#{property}/attributionSettings")),
+          channel_groups: normalized_resource_list(:list_channel_groups, parent: property),
+          calculated_metrics: normalized_resource_list(:list_calculated_metrics, parent: property),
+          event_create_rules: streams.flat_map do |stream|
+            normalized_resource_list(:list_event_create_rules, parent: stream.name)
+          end,
+          event_edit_rules: streams.flat_map do |stream|
+            normalized_resource_list(:list_event_edit_rules, parent: stream.name)
+          end,
+          bigquery_links: normalized_resource_list(:list_big_query_links, parent: property)
+        )
+      end
+
+      def change_history(property_id, limit: 100, days: 30)
+        validate_bounded_integer!(limit, "history limit", 1, 200)
+        validate_bounded_integer!(days, "history days", 1, 365)
+        property = property_name(property_id)
+        account = property_access(property_id).parent
+        unless account.is_a?(String) && account.match?(%r{\Aaccounts/\d{1,50}\z})
+          raise RemoteError, "Google Admin API returned an invalid parent account"
+        end
+
+        now = Time.now.utc
+        events = list_first(
+          :search_change_history_events,
+          {
+            account:,
+            property:,
+            earliest_change_time: now - (days * 86_400),
+            latest_change_time: now,
+            page_size: limit
+          },
+          limit
+        ).map { |event| normalize_change_history_event(event) }
+        Governance::ChangeHistory.new(property_id:, events:)
+      end
+
+      def access_report(property_id, date_ranges:, limit: 1_000)
+        validate_bounded_integer!(limit, "access report limit", 1, 100_000)
+        unless date_ranges.is_a?(Array) && date_ranges.length.between?(1, 2)
+          raise InvalidRequestError, "Access report requires one or two date ranges"
+        end
+
+        response = get(
+          :run_access_report,
+          entity: property_name(property_id),
+          dimensions: [{ dimension_name: "accessDateHour" }],
+          metrics: [{ metric_name: "dataApiQuotaPropertyTokensConsumed" }],
+          date_ranges: date_ranges.map do |range|
+            { start_date: range.fetch("start_date"), end_date: range.fetch("end_date") }
+          end,
+          limit:,
+          return_entity_quota: true,
+          include_all_users: false,
+          expand_groups: false
+        )
+        normalize_access_report(property_id, response)
+      rescue KeyError
+        raise InvalidRequestError, "Access report date range is invalid"
+      end
+
+      private
+
+      def governance_stream_settings(streams)
+        streams.map do |stream|
+          Governance::StreamSettings.new(
+            stream_id: stream.id,
+            stream_name: stream.name,
+            enhanced_measurement: resource_hash(
+              get(:get_enhanced_measurement_settings, name: "#{stream.name}/enhancedMeasurementSettings")
+            ),
+            data_redaction: resource_hash(
+              get(:get_data_redaction_settings, name: "#{stream.name}/dataRedactionSettings")
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/analytics_ops/clients/admin_governance_normalization.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Clients
+    # Normalizes experimental governance, access, and history API responses.
+    module AdminGovernanceNormalization
+      private
+
+      def normalized_resource_list(method_name, parent:)
+        list(method_name, parent:, page_size: 200)
+          .map { |item| resource_hash(item) }
+          .sort_by { |item| item.fetch("name", "") }
+      end
+
+      def normalize_change_history_event(value)
+        event = resource_hash(value)
+        raw_changes = Array(event["changes"])
+        if raw_changes.length > 1_000
+          raise RemoteError, "Google Admin API returned too many changes in one history event"
+        end
+
+        filtered = event.fetch("changes_filtered", false)
+        unless [true, false].include?(filtered)
+          raise RemoteError, "Google Admin API returned an invalid change-history filter flag"
+        end
+
+        {
+          "id" => remote_string(event["id"], "change-history ID"),
+          "change_time" => remote_string(event["change_time"], "change-history time"),
+          "actor_type" => remote_string(event["actor_type"], "change-history actor type"),
+          "changes_filtered" => filtered,
+          "changes" => raw_changes.map { |change| normalize_history_change(change) }
+        }
+      end
+
+      def normalize_history_change(change)
+        raise RemoteError, "Google Admin API returned an invalid change-history change" unless change.is_a?(Hash)
+
+        {
+          "resource" => remote_string(change["resource"], "changed resource"),
+          "action" => remote_string(change["action"], "change action")
+        }
+      end
+
+      def normalize_access_report(property_id, response)
+        dimensions = access_headers(response, :dimension_headers, :dimension_name, "access dimension header")
+        metrics = access_headers(response, :metric_headers, :metric_name, "access metric header")
+        headers = dimensions + metrics
+        rows = array_field(response, :rows).map { |row| normalize_access_row(row, headers) }
+        row_count = field(response, :row_count)
+        unless row_count.is_a?(Integer) && row_count >= rows.length
+          raise RemoteError, "Google Admin API returned an invalid access row count"
+        end
+
+        Governance::AccessReport.new(
+          property_id:,
+          dimension_headers: dimensions,
+          metric_headers: metrics,
+          rows:,
+          row_count:,
+          quota: field(response, :quota) ? resource_hash(field(response, :quota)) : {}
+        )
+      end
+
+      def access_headers(response, collection, field_name, label)
+        array_field(response, collection).map do |header|
+          remote_string(field(header, field_name), label)
+        end
+      end
+
+      def normalize_access_row(row, headers)
+        values = array_field(row, :dimension_values).map do |item|
+          remote_string(field(item, :value), "access dimension value")
+        end
+        values += array_field(row, :metric_values).map do |item|
+          remote_string(field(item, :value), "access metric value")
+        end
+        raise RemoteError, "Google Admin API returned an invalid access row" unless values.length == headers.length
+
+        headers.zip(values).to_h
+      end
+
+      def validate_bounded_integer!(value, label, minimum, maximum)
+        return if value.is_a?(Integer) && value.between?(minimum, maximum)
+
+        raise InvalidRequestError, "#{label} must be between #{minimum} and #{maximum}"
+      end
+    end
+  end
+end

data/lib/analytics_ops/clients/admin_resource_normalization.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AnalyticsOps
+  module Clients
+    # Strictly normalizes generated Google resource values into gem-owned data.
+    module AdminResourceNormalization
+      private
+
+      def resource_hash(value)
+        raw = value.respond_to?(:to_h) ? value.to_h : value
+        normalized_remote_value(raw, depth: 0)
+      end
+
+      def normalized_remote_value(value, depth:)
+        raise RemoteError, "Google Admin API returned an excessively nested resource" if depth > 16
+
+        case value
+        when Hash then normalize_remote_hash(value, depth)
+        when Array then normalize_remote_array(value, depth)
+        when String then remote_string(value, "resource value")
+        when Symbol then normalize_enum(value)
+        when Integer, TrueClass, FalseClass, NilClass then value
+        when Float then normalize_remote_float(value)
+        else normalize_remote_object(value, depth)
+        end
+      end
+
+      def normalize_remote_hash(value, depth)
+        raise RemoteError, "Google Admin API returned an oversized resource" if value.length > 1_000
+
+        value.to_h do |key, child|
+          name = key.to_s
+          unless name.match?(/\A[a-zA-Z][a-zA-Z0-9_]{0,127}\z/)
+            raise RemoteError, "Google Admin API returned an invalid resource field"
+          end
+
+          [name, normalized_remote_value(child, depth: depth + 1)]
+        end
+      end
+
+      def normalize_remote_array(value, depth)
+        raise RemoteError, "Google Admin API returned an oversized resource array" if value.length > 10_000
+
+        value.map { |child| normalized_remote_value(child, depth: depth + 1) }
+      end
+
+      def normalize_remote_float(value)
+        raise RemoteError, "Google Admin API returned a non-finite resource value" unless value.finite?
+
+        value
+      end
+
+      def normalize_remote_object(value, depth)
+        return value.to_time.utc.iso8601(9) if value.respond_to?(:to_time)
+        return normalized_remote_value(value.to_h, depth: depth + 1) if value.respond_to?(:to_h)
+
+        raise RemoteError, "Google Admin API returned an unsupported resource value"
+      end
+    end
+  end
+end