sealmetrics 0.1.0

package/PROTOCOL.md

@@ -0,0 +1,85 @@
+# `sealmetrics init --agent` — NDJSON protocol v1
+
+When invoked with `--agent`, **every** stdout line is a single, complete JSON
+object terminated by `\n` (never multiline). Debug logs go to **stderr** only.
+An orchestrating agent parses the stream line by line and renders progress,
+diffs and the claim URL to its user.
+
+## Envelope
+
+```json
+{ "v": 1, "type": "lifecycle", "level": "info", "data": { } }
+```
+
+| Field   | Meaning |
+|---------|---------|
+| `v`     | Protocol version (currently `1`). Bumped on breaking changes so parsers can branch. |
+| `type`  | `lifecycle` \| `file_change` \| `needs_input` \| `result` \| `error` |
+| `level` | `info` \| `warn` \| `error` |
+| `data`  | Type-specific payload (below). |
+
+## Event types
+
+### `lifecycle`
+Milestones. `data.stage` is the milestone id; extra fields vary.
+
+```
+start · detected:<framework|platform> · provisioned · reused
+handoff:inject · handoff:plugin · handoff:already-installed · handoff:manual
+verified:local · verify:local-pending
+mcp:configured · mcp:handoff
+instrumentation_guide · verified:pixel · verify:pending
+```
+
+Notable payloads:
+- `detected:*` → `{ framework, platform, strategy, recommended_location, provision_only }`
+- `provisioned` → `{ account_id, dashboard_url, claim_url, free_quota_events }` (**never** the api_key)
+- `handoff:inject` → `{ snippet, recommended_location, placement_hint, install_md }` — the **agent** places the snippet
+- `instrumentation_guide` → `{ guide_path }`
+
+### `file_change`
+One per file the CLI plans/writes. The CLI only ever writes **its own**
+artefacts (`.env`, `seal.config.json`, `.sealmetrics/*`, MCP config, `.gitignore`)
+— never app source.
+
+```json
+{ "v":1, "type":"file_change", "level":"info",
+  "data": { "path": ".env", "action": "plan", "diff": "+ SEALMETRICS_API_KEY=…", "bytes": 42 } }
+```
+`action` is `plan` (with `diff`) before the write and `applied` after.
+
+### `needs_input`
+In `--agent` every prompt is **auto-resolved** (from flags or a safe default)
+and the resolution is reported — the stream never blocks on stdin.
+
+```json
+{ "v":1, "type":"needs_input", "level":"info",
+  "data": { "id":"…", "prompt":"…", "default":"…", "resolved":"…" } }
+```
+
+### `result`
+The final structured payload.
+
+```json
+{ "v":1, "type":"result", "level":"info",
+  "data": { "account_id":"…", "dashboard_url":"…", "claim_url":"…",
+            "framework":"next-app", "mcp_configured": true, "verified": true,
+            "next_steps": ["…"] } }
+```
+
+### `error`
+```json
+{ "v":1, "type":"error", "level":"error",
+  "data": { "code":"AUTH_REQUIRED", "message":"…", "hint":"…", "command":"npx sealmetrics init --provision-key <KEY> …" } }
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | OK |
+| `2`  | Invalid args |
+| `3`  | `AUTH_REQUIRED` — provision key invalid/revoked (`error.data.command` carries the re-invocation) |
+| `4`  | Network / backend unavailable / rate-limited / kill-switch (503) |
+| `5`  | Verify-failed — snippet placed but pixel did not confirm within the timeout |
+| `130`| Cancelled (SIGINT) |

package/README.md

@@ -0,0 +1,63 @@
+# sealmetrics
+
+Set up [SealMetrics](https://sealmetrics.com) analytics in one command: provision
+a free account, get the tracker snippet placed, and auto-configure the SealMetrics
+MCP server in your editor so you can read your analytics in natural language.
+
+```bash
+npx sealmetrics init
+```
+
+Privacy-first, cookieless, GDPR-compliant by design — no card required for the
+free tier.
+
+## What it does
+
+1. **Detects** your framework (Next.js, Astro, Remix, Nuxt, SvelteKit, Vite,
+   plain HTML) or CMS (WordPress, WooCommerce, PrestaShop, …).
+2. **Provisions** a free account headless (`POST /provision`) and stores the
+   read-only API key in `.env` (gitignored — never printed).
+3. **Hands off the snippet** — the CLI **never edits your source**. It tells you
+   exactly where the snippet goes and writes `.sealmetrics/INSTALL.md`; you (or
+   your agent) paste it.
+4. **Auto-configures the MCP server** for Claude Code, Cursor, Windsurf or
+   VS Code (unknown clients get the standard block to paste).
+5. **Verifies** the install by polling pixel status.
+
+## Agent mode
+
+```bash
+npx sealmetrics init --agent --email you@example.com --accept-tos \
+  --site-name "My Shop" --domain myshop.com --install-source claude-code
+```
+
+In `--agent` mode all stdout is versioned NDJSON with structured exit codes — see
+[PROTOCOL.md](./PROTOCOL.md). Built for AI orchestrators (Claude Code, Cursor,
+Codex) to drive in one turn.
+
+## Common flags
+
+| Flag | Purpose |
+|------|---------|
+| `--agent` | Machine mode (NDJSON + auto-approve, no prompts) |
+| `-y, --yes` | Non-interactive (use flags/defaults) |
+| `--dry-run` | Detect only — no provisioning, no writes |
+| `--resume` | Resume from the last checkpoint (no re-provision) |
+| `--no-inject` | Provision only — don't emit placement guidance |
+| `--no-mcp` | Skip MCP auto-config |
+| `--region <prod\|pre\|local>` / `--base-url <url>` | Target a backend |
+| `--editor <id>` | Force an MCP client |
+| `--verify-timeout <secs>` | Pixel verify timeout (0 = skip) |
+
+Run `npx sealmetrics init --help` for the full list.
+
+## What it writes
+
+Only its **own** artefacts, always atomically and idempotently:
+`.env`, `seal.config.json`, `.sealmetrics/INSTALL.md`,
+`.sealmetrics/INSTRUMENTATION.md`, `.sealmetrics/checkpoint.json`, the MCP config
+file, and `.gitignore` entries. It never touches your application source.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "sealmetrics",
+  "version": "0.1.0",
+  "description": "SealMetrics setup CLI — provision a free analytics account, place the tracker, and auto-configure the MCP server in one turn",
+  "author": "SealMetrics <dev@sealmetrics.com> (https://sealmetrics.com)",
+  "homepage": "https://github.com/adinton/sealmetrics2/tree/main/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adinton/sealmetrics2.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/adinton/sealmetrics2/issues"
+  },
+  "type": "module",
+  "bin": {
+    "sealmetrics": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "PROTOCOL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "sync-guide": "node scripts/sync-guide.mjs",
+    "prebuild": "node scripts/sync-guide.mjs",
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "pretest": "node scripts/sync-guide.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && chmod +x dist/index.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "4.1.5"
+  },
+  "keywords": [
+    "sealmetrics",
+    "analytics",
+    "cli",
+    "setup",
+    "wizard",
+    "mcp",
+    "privacy-first",
+    "cookieless"
+  ],
+  "license": "MIT"
+}