@contentsquare/wizard 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +81 -0
- package/dist/cli.js +1187 -0
- package/dist/cli.js.map +1 -0
- package/package.json +56 -0
- package/skills/wizard-web-tag-install.md +361 -0
package/README.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# @contentsquare/wizard
|
|
2
|
+
|
|
3
|
+
AI-assisted Contentsquare tag installation and configuration. A standalone CLI that drops a skill into your project for your AI coding agent (GitHub Copilot, Cursor, Claude Code) to install the Contentsquare tag, plus a `verify` command that opens your app in a real browser and confirms the tag, CSP, and pageview coverage in one session.
|
|
4
|
+
|
|
5
|
+
## Quickstart
|
|
6
|
+
|
|
7
|
+
Inside your web project, run:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx @contentsquare/wizard start
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
That single command:
|
|
14
|
+
|
|
15
|
+
1. Resolves your **tag ID** — pass `--tag-id <hashed>` (hex, e.g. `81c677ba742d7`), or answer the prompt.
|
|
16
|
+
2. Creates `.cs-wizard/` with `state.json` and the `wizard-web-tag-install.md` skill.
|
|
17
|
+
3. Adds `.cs-wizard/` to your `.gitignore`.
|
|
18
|
+
4. Copies a prompt to your clipboard to paste into your agent.
|
|
19
|
+
|
|
20
|
+
Then open your project in your editor and tell your agent:
|
|
21
|
+
|
|
22
|
+
> Read and follow .cs-wizard/skills/wizard-web-tag-install.md
|
|
23
|
+
|
|
24
|
+
The agent detects your framework, installs `@contentsquare/tag-sdk`, wires up the init code, and verifies the result by running `npx @contentsquare/wizard verify`.
|
|
25
|
+
|
|
26
|
+
> `install` is an alias of `start` — both run the same flow, so use whichever you prefer.
|
|
27
|
+
|
|
28
|
+
### Prerequisites
|
|
29
|
+
|
|
30
|
+
- Node.js >= 18 (npm and `npx` ship with Node).
|
|
31
|
+
- An AI coding agent (GitHub Copilot in VS Code, Cursor, or Claude Code).
|
|
32
|
+
- For `verify`: a desktop with a graphical display. It uses your installed Chrome/Edge, or downloads Chromium on demand with `--install-browser`.
|
|
33
|
+
|
|
34
|
+
### Why `npx` is enough
|
|
35
|
+
|
|
36
|
+
You never need to install this package globally — `npx @contentsquare/wizard …` resolves the package on demand (cached after the first run). No PATH setup, no global install, no version drift between projects.
|
|
37
|
+
|
|
38
|
+
> **Tip:** if you'd rather type `wizard-cs verify` than `npx @contentsquare/wizard verify`, install once globally with `npm i -g @contentsquare/wizard`. The bin is `wizard-cs` (scoped to avoid clashing with other tools named `wizard`).
|
|
39
|
+
|
|
40
|
+
## Commands
|
|
41
|
+
|
|
42
|
+
| Command | Description |
|
|
43
|
+
| ---------------------------------- | ------------------------------------------------------------------------------ |
|
|
44
|
+
| `npx @contentsquare/wizard start` | Drop the wizard skill into your project (alias: `install`) |
|
|
45
|
+
| `npx @contentsquare/wizard verify` | Open your app in a real browser and verify the tag, CSP, and pageview coverage |
|
|
46
|
+
| `npx @contentsquare/wizard status` | Show the configured tag ID and the latest verification result |
|
|
47
|
+
|
|
48
|
+
### Options
|
|
49
|
+
|
|
50
|
+
`start` / `install`:
|
|
51
|
+
|
|
52
|
+
- `--dir <path>` — Target directory (defaults to cwd)
|
|
53
|
+
- `--tag-id <hashed>` — Hashed Contentsquare tag ID (hex, e.g. `81c677ba742d7`)
|
|
54
|
+
|
|
55
|
+
`verify`:
|
|
56
|
+
|
|
57
|
+
- `--dir <path>` — Project directory (defaults to cwd)
|
|
58
|
+
- `--url <url>` — App URL to open (skips the prompt)
|
|
59
|
+
- `--tag-id <hashed>` — Tag ID to check against (defaults to wizard state)
|
|
60
|
+
- `--install-browser` — Auto-download the Chromium engine if no browser is found
|
|
61
|
+
- `--preflight` — Check browser availability and environment, then exit (diagnostics)
|
|
62
|
+
- `--json` — Emit the report as JSON to stdout (for agents)
|
|
63
|
+
|
|
64
|
+
## How verification works
|
|
65
|
+
|
|
66
|
+
`verify` launches a real browser window with a Contentsquare banner overlaid on your app. You browse — let the first page load, click through a few in-app routes, log in if needed — then click **Done** (or close the window). It then prints a report covering:
|
|
67
|
+
|
|
68
|
+
- whether the tag script loaded (`t.contentsquare.net/uxa/<tagId>.js`),
|
|
69
|
+
- whether the first pageview fired,
|
|
70
|
+
- pageview coverage across the routes you navigated, and
|
|
71
|
+
- any CSP violations referencing Contentsquare domains.
|
|
72
|
+
|
|
73
|
+
The same report is written to `.cs-wizard/last-report.json`, and `status` summarizes the latest run.
|
|
74
|
+
|
|
75
|
+
## Skill
|
|
76
|
+
|
|
77
|
+
`start` copies a single self-contained skill into `.cs-wizard/skills/`:
|
|
78
|
+
|
|
79
|
+
- **wizard-web-tag-install.md** — Guides the agent to detect the framework, install `@contentsquare/tag-sdk`, add the browser-only init code (Next.js, React, Vue, Nuxt, Angular, SvelteKit, static HTML / server-rendered), run `verify`, and fix CSP only when `verify` reports a violation.
|
|
80
|
+
|
|
81
|
+
Configuration that requires the Contentsquare app UI (e.g. **Tracking URL Changes** mode for SPA route changes) is **not** performed by this wizard. When `verify` returns `pass-with-recommendation`, it surfaces that as a recommendation for the developer to complete in the app.
|