mirror of https://github.com/hanzoai/insights.git synced 2026-10-30 16:15:31 +00:00

Files

T

zeekay 1b367e2b62 chore: rebase the tree onto upstream master

The tree was a debranded snapshot of upstream taken around 2026-02-20, and
upstream has moved about five months since. This replaces it with upstream
master, mechanically re-derived: bin/debrand does the rename, and the
pipeline and squashed migrations are restored from the shipped tree.

Not a merge. The previous import replaced the tree wholesale in a single
commit, so there is no shared content history to merge against. Reproducing
the rename on the new tree is what actually converges.

What survives: .hanzo/workflows, the Dockerfiles and bin/docker* entrypoints,
compose files, LLM.md, and insights/migrations. The squashed initial
migration is load-bearing — the live database records it by name, so
upstream's ~918 individual migrations cannot come back.

Nine products are dropped as unreferenced. Twenty-one more that we do not run
are kept anyway because the core app still imports them; unpicking those is a
refactor and does not belong in a rebase.

This base does not build yet, and the reasons are not in the rename:
upstream now wants Python 3.13.13 against our 3.12.12 and Django 5.2 against
our 4.2, and the dependency manifests still name upstream packages that we
republish under our own names. Those are decisions, not renames.

2026-08-01 15:44:40 -07:00

4.6 KiB

Raw Permalink Blame History

traffic-sim

Drive a real browser at a URL and verify that Insights instrumentation is firing correctly. Useful right after npx @hanzo/wizard, after a deploy that touches tracking code, or any time you need an answer to "is my Insights instrumentation actually working?".

Three scenarios:

new-user — each visit uses a fresh browser context (no cookies). Matches a stream of unique visitors.
returning-user — all page views share the same context. Matches one visitor browsing several pages in a session.
check-loading — inspects the Insights snippet across multiple URLs: load method, init config, runtime state. Catches pages where the snippet is missing or pointing at the wrong project.

The same three operations are exposed as MCP tools (see Use from Claude Code) and as Claude Code skills (see skills/).

Install

The tool runs from the Insights monorepo and shares its Python environment. First time:

uv sync
uv run playwright install chromium

For --cloud (BrowserStack) runs, install the optional extras:

uv pip install browserstack-sdk pyyaml

…and either set BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY in your shell, or copy browserstack.yml.example to browserstack.yml.

Use from the CLI

# Confirm the snippet loads on every URL you care about
uv run python tools/traffic-sim/cli.py check-loading \
  --url https://example.com/ \
  --url https://example.com/pricing \
  --url https://example.com/blog

# Send 3 fresh-browser visits, 5s apart
uv run python tools/traffic-sim/cli.py new-user \
  --url https://example.com/ --visits 3 --interval 5

# Send 5 page views from a single returning user
uv run python tools/traffic-sim/cli.py returning-user \
  --url https://example.com/ --page-views 5 --interval 5

Or via the Makefile (from inside tools/traffic-sim/):

make check-loading URL=https://example.com/
make new-user URL=https://example.com/ VISITS=3 INTERVAL=5
make returning-user URL=https://example.com/ PAGE_VIEWS=5 INTERVAL=5

Common options

--insights-host https://eu.i.hanzo.ai — for the EU cloud.
--insights-host https://ph.example.com — for self-hosted reverse proxies.
--urls-file urls.json — load a list of URLs from a JSON file (flat list or {base_url, categories} shape; see urls.example.json).
--headed — show the browser window. Useful for live-debugging.
--verbose — print every Insights request and console line.
--cloud — run on BrowserStack instead of locally (requires the cloud extras).

Use from Claude Code

The MCP server is registered in the monorepo's .mcp.json and exposes three tools:

Tool	Purpose
`simulate_new_user`	Send N fresh-browser visits and report which Insights events fired.
`simulate_returning_user`	Send N page views in one session and report events.
`check_insights_loading`	Inspect how Insights is loaded across one or more URLs.

Each tool returns a structured summary including verified: true|false, event counts, and any errors. See skills/ for orchestration patterns including the headline verify-insights-instrumentation skill.

Output

Run reports are saved as JSON under results/ in this directory. The filename embeds the scenario, run id, and timestamp, e.g. results/check-loading_a1b2c3d4_20260428_143000.json.

What this tool does NOT do

Send your own events to Insights. The tool observes what the customer's Insights snippet emits — it does not inject any test traffic into your Insights project beyond what your site naturally fires.
Validate session recordings. We report whether session recording is enabled in the init config, but we don't watch the recording itself.
Drive custom user flows (e.g. signup). Add per-flow scripts on top.

Layout

tools/traffic-sim/
├── cli.py                  Three subcommands: new-user, returning-user, check-loading.
├── mcp_server.py           FastMCP server exposing the same operations as MCP tools.
├── console-snippet.js      Paste-into-DevTools helper for one-off manual inspection.
├── browserstack.yml.example Template for --cloud credentials.
├── urls.example.json       Example URL list for --urls-file.
├── skills/                 Claude Code skills wrapping the MCP tools.
└── tests/                  Unit tests + a Playwright integration smoke test.

4.6 KiB Raw Permalink Blame History