@inizioevoke/veeva-astroclm-core 1.1.0 → 1.1.1

package/agents/claude/analytics-auditor/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: analytics-auditor
+description: >
+  Starts the Astro dev server, visits every page, clicks configurable CSS selectors,
+  captures all browser console messages, and writes a deduplication report of unique
+  log messages grouped by page. Use this skill whenever the user asks to audit,
+  record, or report on analytics, metrics, or events.
+---
+
+# Analytics Auditor Skill
+
+## Purpose
+
+Start the dev server, click interactive elements, harvest every `console.*` message,
+and produce a report of **unique messages** (grouped by page) written to
+`analytics-audit-report.md` in the project root.
+
+---
+
+## Instructions
+
+### Step 0 — Load the Playwright MCP tool schemas
+
+Before doing anything else, call:
+```
+ToolSearch({ query: "select:mcp__plugin_playwright_playwright__browser_navigate,mcp__plugin_playwright_playwright__browser_click,mcp__plugin_playwright_playwright__browser_console_messages,mcp__plugin_playwright_playwright__browser_snapshot,mcp__plugin_playwright_playwright__browser_wait_for,mcp__plugin_playwright_playwright__browser_evaluate,mcp__plugin_playwright_playwright__browser_handle_dialog,mcp__plugin_playwright_playwright__browser_close" })
+```
+
+You will need all of those tools to be loaded and callable.
+
+---
+
+### Step 1 — Start the dev server and detect its port
+
+Astro auto-increments the port when the default (4321) is already in use, so never
+assume a fixed port. Instead, capture the server's own output to read the URL it
+actually binds to.
+
+Run this command to start the server and tee its output to a temp file:
+```bash
+npm run dev > /tmp/astro-dev.log 2>&1 &
+```
+
+Then poll the log file until Astro prints its ready URL. **Do not use `grep -P`** —
+it is not supported on Windows. Use this portable polling loop instead:
+```bash
+for i in $(seq 1 20); do
+  port=$(grep -o 'localhost:[0-9]*' /tmp/astro-dev.log | head -1 | grep -o '[0-9]*$')
+  if [ -n "$port" ]; then echo $port; break; fi
+  sleep 1
+done
+```
+
+Extract the port from that output and use it as `DEV_PORT` for all subsequent URLs
+(e.g. `http://localhost:${DEV_PORT}/home/`).
+
+If the log file already contains a port before you start the server, the server was
+already running — use that port and skip the `npm run dev` step.
+
+---
+
+### Step 2 — Discover pages and define click selectors
+
+#### Page URLs
+
+Do **not** hardcode the page list. Instead, read the `src/pages` directory to discover
+all `.astro` files:
+```bash
+find src/pages -name "*.astro" | sort
+```
+
+Convert each file path to a URL route using these rules:
+- Strip the `src/pages/` prefix and `.astro` extension
+- A file named `index.astro` maps to `/`
+- All other files map to `/<name>/` (trailing slash)
+- Nested files (e.g. `src/pages/about/moa.astro`) map to `/about/moa/`
+
+Prepend `http://localhost:${DEV_PORT}` from Step 1 to form the full URL.
+
+Example — `src/pages/home.astro` → `http://localhost:${DEV_PORT}/home/`
+
+#### Click selectors
+
+On every page, query for all elements matching the following selectors and click each
+one that is visible and not disabled:
+
+```
+a
+button
+[role="button"]
+[role="link"]
+[role="tab"]
+input[type="checkbox"]
+input[type="radio"]
+[role="checkbox"]
+[role="radio"]
+```
+
+Use a single combined CSS selector string joined with commas when querying the page.
+The user may supply additional or replacement selectors in their request — merge them
+into this list rather than replacing it entirely unless the user says otherwise.
+
+---
+
+### Step 3 — Per-page procedure
+
+For **each page URL** discovered in Step 2:
+
+1. Navigate to the page URL.
+2. Wait for the page to load (use `browser_wait_for` with a known selector like `h1`).
+3. **Inject a navigation guard** using `browser_evaluate` to prevent link clicks from
+   navigating away while still allowing the app's own click handlers (including
+   tracking) to run. Use a **bubble-phase** listener so the app's capture-phase and
+   bubble-phase handlers fire first:
+   ```js
+   () => {
+     document.addEventListener('click', (e) => {
+       const a = e.target.closest('a');
+       if (a) e.preventDefault();
+     });
+   }
+   ```
+   This approach ensures tracking events fire before navigation is cancelled.
+   **Do NOT add a `beforeunload` listener** — it causes a "Leave site?" browser dialog
+   that blocks every subsequent Playwright navigation.
+
+4. Take a `browser_snapshot` to get the current accessibility tree. Use the refs from
+   this snapshot for all subsequent clicks on this page.
+
+5. For **each matched element** (visible, not disabled):
+   a. Click it using `browser_click`.
+   b. Wait 500ms for async effects.
+   c. If the click opened a modal or significantly changed the DOM, take a new
+      `browser_snapshot` before proceeding — snapshot refs become stale after DOM
+      changes and will cause errors if reused.
+   d. If a dialog appears (check the snapshot for `Modal state`), dismiss it with
+      `browser_handle_dialog` before continuing.
+
+6. After all clicks on the page, call `browser_console_messages` **once** with
+   `level: "debug"`. Since `all` defaults to `false`, this returns only the messages
+   from the current page navigation — no need to diff between clicks.
+
+7. Store all messages with the page route (e.g. `/home/`) as their source.
+
+---
+
+### Step 4 — Parse, deduplicate, and structure the data
+
+#### Identify tracking events
+
+When an element is clicked the app emits a tracking log in this format:
+```
+[HH:MM:SS.mmm] DEBUG: track {slide: 'home', type: 'button', name: 'button_evo_flip_card_trigger'}
+```
+
+For every console message, check whether its text matches this pattern:
+```
+DEBUG: track {…}
+```
+
+If it matches, parse out the object payload `{ slide, type, name }` — these are the
+primary data points of interest. Store them as structured tracking events separate from
+general log messages.
+
+#### Collect all messages
+
+Gather every console message captured across all pages into a flat list:
+```
+{
+  page: string,           // route, e.g. "/home/"
+  level: "log"|"warn"|"error"|"info"|"debug",
+  text: string,           // full raw message text
+  tracking: {             // only present when the message is a tracking event
+    slide: string,
+    type: string,
+    name: string
+  } | null
+}
+```
+
+#### Deduplicate
+
+Two messages are duplicates if they share the same `text`. When the same message
+appears on multiple pages, record all pages it appeared on.
+
+#### Tiers
+
+Organize into four tiers:
+1. **Tracking Events** — messages matching the `DEBUG: track` pattern
+2. **Errors** — `console.error`
+3. **Warnings** — `console.warn`
+4. **Info / Log** — `console.log`, `console.info`, `console.debug` (excluding tracking events)
+
+---
+
+### Step 5 — Write the report
+
+Write a Markdown file to `analytics-audit-report.md` in the project root with this structure:
+
+```markdown
+# Browser Console Log Audit
+
+**Date:** <today's date>
+**Pages audited:** /home/, /about/, /about/moa/
+**Total unique messages:** <N>
+
+---
+
+## Tracking Events (<count>)
+
+| Slide | Type | Name | Pages |
+|-------|------|------|-------|
+| `home` | `button` | `button_evo_flip_card_trigger` | /home/ |
+
+## Errors (<count>)
+
+| Message | Pages |
+|---------|-------|
+| `<message text>` | /home/, /about/ |
+
+## Warnings (<count>)
+
+| Message | Pages |
+|---------|-------|
+| `<message text>` | /home/ |
+
+## Info / Log (<count>)
+
+| Message | Pages |
+|---------|-------|
+| `<message text>` | /about/moa/ |
+
+---
+
+*Generated by the analytics-auditor skill.*
+```
+
+If a tier has zero messages, write `_None_` instead of a table.
+
+After writing the file, tell the user where the report was saved and give a brief
+summary (e.g. "Found 8 tracking events, 2 errors, 1 warning, 5 info messages across 3 pages").
+
+---
+
+### Step 6 — Close the browser and clean up
+
+Call `browser_close` when done so the Playwright session is cleaned up.
+
+Then delete the `.playwright-mcp` directory that Playwright creates for snapshots and
+console logs:
+```bash
+rm -rf .playwright-mcp
+```
+
+Do **not** stop the dev server — the user likely wants to keep it running.
+
+---
+
+## Notes
+
+- The Astro dev server defaults to port **4321** but increments on collision — always
+  read the actual port from the server output as described in Step 1.
+- **`grep -P` is not supported on Windows** — use `grep -o` with basic regex patterns.
+- **Snapshot refs go stale** after DOM mutations (modal open/close, tab switches). Always
+  re-snapshot after any click that visibly changes the page structure.
+- **`browser_console_messages` fails if a dialog is showing** — check the snapshot for
+  `Modal state` and dismiss with `browser_handle_dialog` before calling it.
+- **Call `browser_console_messages` once per page** (at the end), not after every click.
+  The default `all: false` scopes results to the current navigation, giving a clean
+  per-page log with no diffing needed.
+- If the user provides their own list of selectors or pages, replace the defaults in
+  Step 2 before proceeding.
+- If a selector does not match any element on a page, log a warning in the report's
+  header section rather than failing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inizioevoke/veeva-astroclm-core",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "",
   "license": "ISC",
   "author": "",