feat(analytics): opt-in Firebase Analytics on generated pages (#93)

* feat(analytics): add opt-in Firebase Analytics to generated pages

Injects the Firebase Analytics module snippet into every generated page
(index, posts, comments) via a shared `firebase_analytics()` Jinja global.

Gated on the FIREBASE_WEB_CONFIG env var (Firebase web config JSON): the
snippet is emitted only when the config is present and carries a
measurementId. Forks leave it unset and ship no analytics — mirroring the
existing owner-only Firebase deploy guard. Wired through the generate-site
action input and the FIREBASE_WEB_CONFIG repo variable in publish.yaml.

The embedded JSON is owner-controlled repo config; '<' is escaped to
neutralize any </script> breakout.

Generated-by: Claude Opus 4.8
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(ci): pass FIREBASE_WEB_CONFIG to renderer step

renderer.py is the last writer of index.html; without the env var the
deployed homepage shipped without the analytics snippet while posts and
comments had it. Closes a gap flagged in PR review.

Generated-by: Claude Opus 4.8
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* ci(lefthook): run full ai-checks on pre-push

pre-push only ran a subset (test + detect-secrets + validate-site),
letting commits push without format/lint/complexity. Collapse it to
`make ai-checks` so the push gate matches the manual gate exactly;
detect-secrets and validate-site already run inside ai-checks.

Generated-by: Claude Opus 4.8
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Ashley Childress <anchildress1@gmail.com>

* ci(lefthook): run long tests on pre-push, not pre-commit's checks

pre-push now runs the slow checks not done at commit time — full tests,
complexity, site validation — instead of redoing format/lint/security
that pre-commit already covers. Drops detect-secrets here since
pre-commit's `make security` already runs it.

Generated-by: Claude Opus 4.8
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Ashley Childress <anchildress1@gmail.com>

---------

Signed-off-by: Ashley Childress <anchildress1@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: anchildress1

.github/actions/generate-site/action.yml

@@ -34,6 +34,10 @@ inputs:
     description: Branch holding incremental state (last_run.txt, posts_data.json)
     required: false
     default: gh-pages
+  firebase_web_config:
+    description: Firebase web app config as JSON; enables Analytics injection when set
+    required: false
+    default: ""
   fallback_site_url:
     description: >-
       Base URL (with trailing slash) for robots.txt/sitemap when site_domain is
@@ -108,6 +112,7 @@ runs:
         DEVTO_KEY: ${{ inputs.devto_key }}
         PAGES_REPO: ${{ inputs.pages_repo }}
         FORCE_FULL_REGEN: ${{ inputs.force_full_regen }}
+        FIREBASE_WEB_CONFIG: ${{ inputs.firebase_web_config }}
       run: |
         {
           echo "## 🏗️ Site Generation"
@@ -162,6 +167,10 @@ runs:
     - name: Generate sitemap and index
       if: steps.generate.outputs.no_new_posts != 'true'
       shell: bash
+      # renderer.py is the last writer of index.html, so it needs the analytics
+      # config too — otherwise the homepage ships without the snippet.
+      env:
+        FIREBASE_WEB_CONFIG: ${{ inputs.firebase_web_config }}
       run: |
         echo "## 📄 Generating Sitemap" >> "$GITHUB_STEP_SUMMARY"
         uv run python -m devto_mirror.site_generation.renderer

.github/workflows/publish.yaml

@@ -10,6 +10,9 @@ name: Generate and Publish Dev.to Mirror Site
 # - DEVTO_USERNAME: Your Dev.to username (required)
 # - GH_USERNAME: Your GitHub username (required if SITE_DOMAIN not set)
 # - SITE_DOMAIN: Custom domain for the site (optional)
+# - FIREBASE_WEB_CONFIG: Firebase web app config JSON (optional). When set,
+#     the generated pages include the Firebase Analytics snippet. Forks leave
+#     this unset and ship no analytics. This is public web config, not a secret.
 # - GCP_WORKLOAD_IDENTITY_PROVIDER: Full WIF provider resource name
 #     (projects/<num>/locations/global/workloadIdentityPools/<pool>/providers/<provider>)
 # - GCP_DEPLOY_SERVICE_ACCOUNT: Email of the deploy service account
@@ -77,6 +80,7 @@ jobs:
           force_full_regen: ${{ github.event.inputs.force_full_regen || 'false' }}
           state_branch: mirror-state
           fallback_site_url: https://${{ vars.FIREBASE_PROJECT_ID || 'anchildress1' }}.web.app/
+          firebase_web_config: ${{ vars.FIREBASE_WEB_CONFIG }}
 
       - name: Authenticate to Google Cloud
         if: steps.site.outputs.no_new_posts != 'true'

lefthook.yml

@@ -25,10 +25,12 @@ pre-commit:
 pre-push:
   parallel: true
   commands:
+    # The long checks not run at commit time. format/lint/security already
+    # ran in pre-commit, so don't redo them here.
     tests:
       run: make test
-    detect-secrets:
-      run: uv run python scripts/check_detect_secrets.py
+    check-complexity:
+      run: make check-complexity
     validate-site:
       run: uv run python scripts/validate_site_generation.py
     actionlint:

src/devto_mirror/core/utils.py

@@ -2,11 +2,14 @@
 Shared utilities for devto-mirror scripts
 """
 
+import json
+import os
 import pathlib
 from datetime import datetime, timezone
 from email.utils import parsedate_to_datetime
 
 from jinja2 import Environment, FileSystemLoader, select_autoescape
+from markupsafe import Markup
 
 # Use a Jinja environment with autoescape enabled for HTML/XML templates
 # Also add FileSystemLoader to load templates from files
@@ -16,6 +19,42 @@
     autoescape=select_autoescape(["html", "xml"]),
 )
 
+FIREBASE_SDK_VERSION = "12.15.0"
+
+_FIREBASE_ANALYTICS_TMPL = """<!-- Firebase Analytics -->
+<script type="module">
+  import {{ initializeApp }} from "https://www.gstatic.com/firebasejs/{version}/firebase-app.js";
+  import {{ getAnalytics }} from "https://www.gstatic.com/firebasejs/{version}/firebase-analytics.js";
+  const app = initializeApp({config});
+  getAnalytics(app);
+</script>"""
+
+
+def firebase_analytics_snippet():
+    """Build the Firebase Analytics script tag from FIREBASE_WEB_CONFIG.
+
+    Returns safe markup for the snippet, or empty markup when the env var is
+    unset/invalid or carries no measurementId. Forks without their own
+    configured project therefore ship no analytics.
+    """
+    raw = os.getenv("FIREBASE_WEB_CONFIG", "").strip()
+    if not raw:
+        return Markup("")
+    try:
+        config = json.loads(raw)
+    except (ValueError, TypeError):
+        return Markup("")
+    if not isinstance(config, dict) or not config.get("measurementId"):
+        return Markup("")
+    # Owner-controlled repo variable, not user input; escaping "<" neutralizes
+    # any </script> breakout so the embedded JSON is inert regardless of source.
+    config_json = json.dumps(config).replace("<", "\\u003c")
+    return Markup(_FIREBASE_ANALYTICS_TMPL.format(version=FIREBASE_SDK_VERSION, config=config_json))  # nosec B704
+
+
+# Expose to all templates rendered through this env; evaluated at render time.
+env.globals["firebase_analytics"] = firebase_analytics_snippet
+
 
 # Load post template from file if available, otherwise use inline template
 def get_post_template():
@@ -88,6 +127,7 @@ def get_post_template():
 </script>
 {% endfor %}
 {% endif %}
+{{ firebase_analytics() }}
 </head><body>
 <main>
   <h1><a href="{{ canonical }}">{{ title }}</a></h1>
@@ -191,6 +231,7 @@ def get_post_template():
 <!-- Additional Social Meta -->
 <meta name="image" content="{{ social_image }}">
 <meta name="author" content="{{ username }}">
+{{ firebase_analytics() }}
 </head><body>
 <main>
   <h1>{{ username }}—Dev.to Mirror</h1>

src/devto_mirror/site_generation/generator.py

@@ -18,7 +18,13 @@
 from devto_mirror.core.path_utils import sanitize_filename, sanitize_slug, validate_safe_path
 from devto_mirror.core.run_state import get_last_run_timestamp, mark_no_new_posts, set_last_run_timestamp
 from devto_mirror.core.url_utils import build_site_urls
-from devto_mirror.core.utils import INDEX_TMPL, SITEMAP_TMPL, dedupe_posts_by_link, get_post_template
+from devto_mirror.core.utils import (
+    INDEX_TMPL,
+    SITEMAP_TMPL,
+    dedupe_posts_by_link,
+    firebase_analytics_snippet,
+    get_post_template,
+)
 
 # Import AI optimization components
 try:
@@ -79,6 +85,7 @@
 # Templates (posts + index)
 # ----------------------------
 env = Environment(autoescape=select_autoescape(["html", "xml"]))
+env.globals["firebase_analytics"] = firebase_analytics_snippet
 
 # Get the post template (from file or inline fallback)
 PAGE_TMPL = get_post_template()
@@ -129,6 +136,7 @@
 </script>
 {% endfor %}
 {% endif %}
+{{ firebase_analytics() }}
 </head><body>
 <main>
   <h1>{{ title }}</h1>

src/devto_mirror/templates/post_template.html

@@ -52,6 +52,7 @@
 </script>
 {% endfor %}
 {% endif %}
+{{ firebase_analytics() }}
 </head><body>
 <main>
   <h1><a href="{{ canonical }}">{{ title }}</a></h1>

tests/test_core_utils.py

@@ -309,5 +309,38 @@ def test_sorted_newest_first(self):
         self.assertGreaterEqual(activity_0, activity_1)
 
 
+class TestFirebaseAnalyticsSnippet(unittest.TestCase):
+    VALID_CONFIG = '{"apiKey": "abc", "projectId": "demo", "measurementId": "G-TEST123"}'
+
+    def test_empty_when_env_unset(self):
+        with patch.dict("os.environ", {}, clear=False):
+            import os
+
+            os.environ.pop("FIREBASE_WEB_CONFIG", None)
+            self.assertEqual(str(utils_module.firebase_analytics_snippet()), "")
+
+    def test_empty_on_invalid_json(self):
+        with patch.dict("os.environ", {"FIREBASE_WEB_CONFIG": "not json"}):
+            self.assertEqual(str(utils_module.firebase_analytics_snippet()), "")
+
+    def test_empty_without_measurement_id(self):
+        with patch.dict("os.environ", {"FIREBASE_WEB_CONFIG": '{"apiKey": "abc"}'}):
+            self.assertEqual(str(utils_module.firebase_analytics_snippet()), "")
+
+    def test_renders_snippet_when_configured(self):
+        with patch.dict("os.environ", {"FIREBASE_WEB_CONFIG": self.VALID_CONFIG}):
+            snippet = str(utils_module.firebase_analytics_snippet())
+        self.assertIn("getAnalytics", snippet)
+        self.assertIn("G-TEST123", snippet)
+        self.assertIn(utils_module.FIREBASE_SDK_VERSION, snippet)
+
+    def test_injected_into_index_template(self):
+        with patch.dict("os.environ", {"FIREBASE_WEB_CONFIG": self.VALID_CONFIG}):
+            html = utils_module.INDEX_TMPL.render(
+                username="u", posts=[], comments=[], canonical="https://x", home="https://x", site_description=""
+            )
+        self.assertIn("G-TEST123", html)
+
+
 if __name__ == "__main__":
     unittest.main()