analytics_ops 0.1.0

data/docs/commands.md

@@ -0,0 +1,112 @@
+# Commands
+
+The executable is `analytics-ops`. All commands use
+`config/analytics_ops.yml` and the `production` profile unless overridden.
+
+```text
+analytics-ops COMMAND [options]
+```
+
+## Fast examples
+
+```bash
+analytics-ops doctor
+analytics-ops audit --format json
+analytics-ops plan --output tmp/ga4-plan.json
+analytics-ops apply tmp/ga4-plan.json
+analytics-ops report landing_pages --format csv
+analytics-ops realtime --format json
+```
+
+Only `apply` can write to Google.
+
+## Read-only commands
+
+| Command | Result |
+| --- | --- |
+| `doctor` | Checks the local file, credentials, Admin API, Data API, property access, client versions, edit visibility, and clock |
+| `discover` | Lists accessible account IDs, property IDs, and stream IDs |
+| `snapshot` | Prints normalized managed remote state and its fingerprint |
+| `audit` | Compares desired state with a fresh snapshot; exits 2 for drift |
+| `plan` | Generates the same comparison; `--output FILE` saves its exact JSON |
+| `verify` | Replans and exits 0 only when managed state converges |
+| `report NAME` | Runs one built-in standard Data API report |
+| `realtime [NAME]` | Runs `realtime_events` by default |
+| `schema` | Prints the version-1 configuration schema |
+
+`doctor` cannot reliably inspect scopes inside an issued Google token. It
+reports that check as unknown and proves effective access with real read-only
+calls instead.
+
+## Apply
+
+```bash
+analytics-ops apply PLAN_FILE
+```
+
+Interactive apply:
+
+1. Loads and strictly validates the saved plan.
+2. Prints every saved before value, after value, and rollback instruction.
+3. Requires the exact response `yes`.
+4. Refreshes the remote snapshot.
+5. Rejects the plan if its fingerprint is stale.
+6. Executes only its saved create/update operations, stopping on first failure.
+
+Automation must be explicit:
+
+```bash
+analytics-ops apply tmp/ga4-plan.json --non-interactive --yes --format json
+```
+
+`--non-interactive` without `--yes` is an error. There is no command that
+plans and applies in one step.
+
+## Options
+
+| Option | Meaning |
+| --- | --- |
+| `-c, --config PATH` | Configuration file |
+| `-p, --profile NAME` | Profile inside the file |
+| `-f, --format FORMAT` | `human`, `json`, or report-only `csv` |
+| `-o, --output PATH` | Save generated JSON; valid only with `plan` |
+| `--transport grpc|rest` | Official Google-client transport |
+| `--timeout SECONDS` | Positive API call timeout |
+| `--log-level LEVEL` | Structured request metadata: `debug`, `info`, `warn`, or `error`; default `warn` |
+| `--yes` | Approve every operation in a saved plan; apply only |
+| `--non-interactive` | Never prompt; apply only and requires `--yes` |
+
+Unknown arguments and options fail instead of being ignored. CSV is rejected
+for anything except report results. CSV cells beginning with spreadsheet
+formula characters are prefixed safely.
+
+## Output
+
+- Human output is readable in a terminal.
+- JSON output uses stable gem-owned fields and structured errors.
+- CSV contains report headers and rows only; it never applies to plans,
+  snapshots, or errors.
+
+No command prints credentials or generated Google protobuf objects. Report
+rows are emitted only because the user requested a report; they are never
+logged automatically.
+
+## Exit statuses
+
+| Status | Meaning |
+| ---: | --- |
+| 0 | Success |
+| 2 | Drift found or verification not converged |
+| 64 | Invalid command, option, argument, or missing confirmation |
+| 65 | Invalid configuration, plan, or ambiguous identity |
+| 66 | Authentication failure |
+| 69 | Invalid Google request or other remote API failure |
+| 74 | Timeout |
+| 75 | Quota or rate limit |
+| 77 | Google Analytics permission failure |
+| 78 | Unsupported installed-client capability |
+| 79 | Stale saved plan |
+| 80 | Partial apply; inspect reconciliation output |
+
+When `--format json` is selected, errors are JSON on standard error and are
+suitable for automation.

data/docs/configuration-schema-v1.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/nelsonchaves/analytics_ops/blob/master/docs/configuration-schema-v1.json",
+  "title": "Analytics Ops configuration version 1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "profiles"],
+  "properties": {
+    "version": { "const": 1 },
+    "profiles": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" },
+      "additionalProperties": { "$ref": "#/$defs/profile" }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^(?:[0-9]{1,50}|\\$\\{[A-Z][A-Z0-9_]*\\})$"
+    },
+    "profile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["property_id"],
+      "properties": {
+        "property_id": { "$ref": "#/$defs/id" },
+        "streams": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" },
+          "additionalProperties": { "$ref": "#/$defs/stream" }
+        },
+        "retention": { "$ref": "#/$defs/retention" },
+        "google_signals": { "$ref": "#/$defs/googleSignals" },
+        "key_events": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" }
+        },
+        "custom_dimensions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/customDimension" }
+        },
+        "custom_metrics": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/customMetric" }
+        },
+        "manual_requirements": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" }
+        }
+      }
+    },
+    "stream": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stream_id"],
+      "properties": {
+        "stream_id": { "$ref": "#/$defs/id" },
+        "default_uri": {
+          "type": "string",
+          "maxLength": 2048,
+          "pattern": "^(?:https?://|\\$\\{)"
+        },
+        "enhanced_measurement": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["enabled", "experimental"],
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "experimental": { "const": true }
+          }
+        }
+      }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["event_data", "user_data", "reset_on_new_activity"],
+      "properties": {
+        "event_data": { "$ref": "#/$defs/retentionValue" },
+        "user_data": { "$ref": "#/$defs/retentionValue" },
+        "reset_on_new_activity": { "type": "boolean" }
+      }
+    },
+    "retentionValue": {
+      "enum": ["2_months", "14_months", "26_months", "38_months", "50_months"]
+    },
+    "googleSignals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "experimental"],
+      "properties": {
+        "state": { "enum": ["enabled", "disabled"] },
+        "experimental": { "const": true }
+      }
+    },
+    "customDimension": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["parameter_name", "display_name", "scope"],
+      "properties": {
+        "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
+        "description": { "type": "string", "maxLength": 150 },
+        "scope": { "enum": ["event", "user", "item"] },
+        "disallow_ads_personalization": { "type": "boolean" }
+      }
+    },
+    "customMetric": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["parameter_name", "display_name", "scope"],
+      "properties": {
+        "parameter_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
+        "display_name": { "type": "string", "minLength": 1, "maxLength": 82 },
+        "description": { "type": "string", "maxLength": 150 },
+        "scope": { "const": "event" },
+        "measurement_unit": {
+          "enum": [
+            "standard", "currency", "feet", "meters", "kilometers", "miles",
+            "milliseconds", "seconds", "minutes", "hours"
+          ]
+        }
+      }
+    }
+  }
+}

data/docs/configuration.md

@@ -0,0 +1,167 @@
+# Configuration
+
+Analytics Ops reads strict, versioned YAML. The file describes desired GA4
+state; it never contains credentials.
+
+## Smallest valid file
+
+```yaml
+version: 1
+
+profiles:
+  production:
+    property_id: "123456789"
+```
+
+Numeric identifiers must stay quoted. `property_id` is a GA4 property ID,
+not account ID `100000001`, stream ID `987654321`, or measurement ID
+`G-EXAMPLE1`.
+
+Use it with:
+
+```bash
+analytics-ops doctor
+analytics-ops audit
+```
+
+The default path is `config/analytics_ops.yml`; the default profile is
+`production`. Change them with `--config` and `--profile`.
+
+## Complete example
+
+All identifiers below are fake:
+
+```yaml
+version: 1
+
+profiles:
+  production:
+    property_id: "${GA4_PROPERTY_ID}"
+
+    streams:
+      web:
+        stream_id: "${GA4_STREAM_ID}"
+        default_uri: "https://www.example.test"
+
+        # Accepted only as an explicit experimental declaration.
+        # Version 0.1.0 reports a finding and does not apply this setting.
+        enhanced_measurement:
+          enabled: true
+          experimental: true
+
+    retention:
+      event_data: 14_months
+      user_data: 14_months
+      reset_on_new_activity: false
+
+    key_events:
+      - calculation_completed
+
+    custom_dimensions:
+      - parameter_name: calculator_slug
+        display_name: Calculator slug
+        description: Published calculator identifier
+        scope: event
+
+      - parameter_name: customer_segment
+        display_name: Customer segment
+        description: Broad non-sensitive segment
+        scope: user
+        disallow_ads_personalization: true
+
+    custom_metrics:
+      - parameter_name: estimate_total
+        display_name: Estimate total
+        description: Non-sensitive calculated estimate
+        scope: event
+        measurement_unit: currency
+
+    # Checklist findings only; Analytics Ops does not claim to manage these.
+    manual_requirements:
+      - email_redaction_enabled
+      - consent_mode_reviewed
+
+    # Explicit declaration only in 0.1.0; never silently applied.
+    google_signals:
+      state: disabled
+      experimental: true
+```
+
+## Managed fields
+
+### Streams
+
+`streams` is keyed by a local readable name. Each entry requires a numeric
+`stream_id`. For a web stream, `default_uri` may be an absolute HTTP or
+HTTPS URI without embedded credentials. Analytics Ops can update an existing
+web stream URI; it does not automatically create or delete streams.
+
+### Retention
+
+All three fields are required when `retention` is present:
+
+- `event_data`: `2_months`, `14_months`, `26_months`, `38_months`, or
+  `50_months`
+- `user_data`: the same values
+- `reset_on_new_activity`: `true` or `false`
+
+Google may restrict longer periods by property type or account capabilities.
+An API rejection is returned as a typed error; Analytics Ops does not silently
+substitute a different period.
+
+### Key events
+
+`key_events` is a unique list of event names. Missing events are created with
+`once_per_event` counting. Existing key events are not deleted or renamed.
+
+### Custom dimensions
+
+Required fields are `parameter_name`, `display_name`, and `scope`.
+Supported scopes are `event`, `user`, and `item`.
+`disallow_ads_personalization` is valid only for user-scoped dimensions.
+
+Identity is `scope + parameter_name`; display name and description are
+mutable. Immutable conflicts are findings, not automatic replacement.
+
+### Custom metrics
+
+Required fields are `parameter_name`, `display_name`, and
+`scope: event`. Units are:
+
+`standard`, `currency`, `feet`, `meters`, `kilometers`, `miles`,
+`milliseconds`, `seconds`, `minutes`, and `hours`.
+
+Identity is `parameter_name`. Scope and unit are immutable; Analytics Ops
+will not archive and recreate a conflicting metric.
+
+## Environment variables
+
+Only the literal form `${UPPER_CASE_NAME}` is expanded, and interpolation
+happens after safe YAML parsing:
+
+```bash
+export GA4_PROPERTY_ID=123456789
+export GA4_STREAM_ID=987654321
+analytics-ops doctor
+```
+
+Missing or malformed variables fail validation. There is no ERB, command
+execution, YAML alias support, or Ruby-object deserialization.
+
+## Strict safety rules
+
+- The file is limited to 1 MiB.
+- Unknown fields fail closed.
+- Secret-shaped fields fail closed at any depth.
+- Numeric identifiers must be YAML strings.
+- User-visible strings reject control characters.
+- Duplicate resource identities fail validation.
+- Configuration loading never contacts Google.
+
+The machine-readable contract is
+[configuration-schema-v1.json](configuration-schema-v1.json). Print the same
+schema from the installed gem with:
+
+```bash
+analytics-ops schema --format json
+```

data/docs/google-client-compatibility.md

@@ -0,0 +1,59 @@
+# Google client compatibility
+
+Analytics Ops uses only Google's official modern Ruby clients. It adds no
+second HTTP stack and does not expose generated Google objects publicly.
+
+## Supported versions
+
+| Direct dependency | Constraint | Contract-tested release |
+| --- | --- | --- |
+| `google-analytics-admin` | `~> 0.8.0` | 0.8.0 |
+| `google-analytics-data` | `~> 0.9.0` | 0.9.0 |
+
+The reviewed lockfile resolves these generated transports:
+
+| Versioned transport | Reviewed release |
+| --- | --- |
+| `google-analytics-admin-v1alpha` | 0.43.0 |
+| `google-analytics-data-v1beta` | 0.22.0 |
+
+The main Admin wrapper currently selects a V1alpha generated transport. That
+transport name does not make every feature Alpha: Google publishes feature
+maturity separately. Analytics Ops treats capabilities Google identifies as
+Alpha as experimental or unsupported.
+
+The pessimistic direct bounds allow reviewed patch updates inside each minor
+line and reject a new minor contract automatically. `doctor` reports the
+installed direct versions, expected bounds, and selected `grpc` or `rest`
+transport.
+
+## Executable contract coverage
+
+Tests coerce deterministic fake requests and responses through official
+protobuf classes for:
+
+- `list_account_summaries`
+- `get_property`
+- `list_data_streams`
+- `get_data_retention_settings`
+- `update_data_retention_settings`
+- `list_key_events` and `create_key_event`
+- list/create/update custom dimensions
+- list/create/update custom metrics
+- update web data-stream default URI
+- `run_report` and `run_realtime_report`
+
+The tests also prove enum mappings and normalization into immutable gem-owned
+values without making network requests.
+
+## Updating a Google client
+
+1. Review the official release and Admin API changelog.
+2. Update one direct bound intentionally.
+3. Resolve the lockfile on every supported Ruby.
+4. Run focused Admin/Data contract specs.
+5. Run the full Ruby and Rails CI matrix.
+6. Update this file and the changelog.
+
+Do not merge an automated client update based only on dependency resolution.
+Generated method, field, enum, and transport changes require contract review.

data/docs/plan-format.md

@@ -0,0 +1,89 @@
+# Saved plan format
+
+`analytics-ops plan --output FILE` writes deterministic version-1 JSON. This
+file is the only mutation input accepted by `apply`.
+
+Example with fake identifiers:
+
+```json
+{
+  "changes": [
+    {
+      "after": {
+        "description": "Published calculator identifier",
+        "disallow_ads_personalization": false,
+        "display_name": "Calculator slug",
+        "parameter_name": "calculator_slug",
+        "scope": "event"
+      },
+      "api_maturity": "beta",
+      "before": null,
+      "operation": "create",
+      "resource_identity": "event:calculator_slug",
+      "resource_type": "custom_dimension",
+      "reversible": true,
+      "rollback": "Archive the newly created custom dimension"
+    }
+  ],
+  "findings": [],
+  "format_version": 1,
+  "profile": "production",
+  "property_id": "123456789",
+  "snapshot_fingerprint": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+}
+```
+
+Plans contain no timestamp. The same desired state and normalized snapshot
+produce the same bytes.
+
+## Top-level fields
+
+| Field | Meaning |
+| --- | --- |
+| `format_version` | Exact plan contract version; currently 1 |
+| `profile` | Configuration profile that produced the plan |
+| `property_id` | Numeric GA4 property ID encoded as a string |
+| `snapshot_fingerprint` | SHA-256 of relevant normalized remote state |
+| `changes` | Sorted supported create/update operations |
+| `findings` | Sorted drift, manual, warning, or experimental observations |
+
+Every change records resource type, stable identity, operation, API maturity,
+before/after payloads, reversibility, and manual rollback guidance.
+
+## Supported version-1 changes
+
+| Resource | Create | Update | Delete/archive |
+| --- | :---: | :---: | :---: |
+| Existing web data-stream default URI | No | Yes | No |
+| Data retention | No | Yes | No |
+| Key event | Yes | No | No |
+| Custom dimension | Yes | Mutable metadata only | No |
+| Custom metric | Yes | Mutable metadata only | No |
+
+Resource names in update payloads must belong to the plan's property. Immutable
+identity fields cannot change between `before` and `after`.
+
+## Findings are not operations
+
+A finding may identify inaccessible resources, immutable conflicts, manual UI
+checks, or explicitly declared experimental capabilities. Apply ignores
+findings; it never converts them into mutations.
+
+## Storage and review
+
+Plan writes are atomic and mode 0600. Treat the file as operationally
+sensitive even though credentials and report rows are forbidden:
+
+```bash
+analytics-ops plan --output tmp/ga4-plan.json
+less tmp/ga4-plan.json
+analytics-ops apply tmp/ga4-plan.json
+```
+
+Do not hand-edit a fingerprint or payload. Generate a new plan after any remote
+or desired-state change. Partial apply also requires reconciliation and a new
+plan.
+
+The complete machine-readable contract is
+[plan-schema-v1.json](plan-schema-v1.json). Runtime validation additionally
+enforces cross-field identity, immutable-field, and cross-property rules.