npm - @jayfarei/lazyanalytics - Versions diffs - 0.1.0 - Mend

@jayfarei/lazyanalytics 0.1.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.

Files changed (35) hide show

package/CHANGELOG.md +27 -0
package/LICENSE +21 -0
package/README.md +210 -0
package/cli/dist/commands/base.d.ts +2 -0
package/cli/dist/commands/base.js +129 -0
package/cli/dist/commands/config.d.ts +2 -0
package/cli/dist/commands/config.js +45 -0
package/cli/dist/commands/setup.d.ts +2 -0
package/cli/dist/commands/setup.js +155 -0
package/cli/dist/commands/sites.d.ts +2 -0
package/cli/dist/commands/sites.js +127 -0
package/cli/dist/commands/skill.d.ts +2 -0
package/cli/dist/commands/skill.js +28 -0
package/cli/dist/commands/snippet.d.ts +2 -0
package/cli/dist/commands/snippet.js +48 -0
package/cli/dist/commands/usage.d.ts +2 -0
package/cli/dist/commands/usage.js +156 -0
package/cli/dist/index.d.ts +2 -0
package/cli/dist/index.js +31 -0
package/cli/dist/lib/api.d.ts +9 -0
package/cli/dist/lib/api.js +27 -0
package/cli/dist/lib/env.d.ts +15 -0
package/cli/dist/lib/env.js +81 -0
package/cli/dist/lib/paths.d.ts +16 -0
package/cli/dist/lib/paths.js +54 -0
package/cli/dist/lib/prompt.d.ts +8 -0
package/cli/dist/lib/prompt.js +42 -0
package/cli/dist/lib/scaffold.d.ts +5 -0
package/cli/dist/lib/scaffold.js +21 -0
package/cli/dist/lib/wrangler.d.ts +17 -0
package/cli/dist/lib/wrangler.js +65 -0
package/dist/worker.js +3221 -0
package/package.json +58 -0
package/skill/SKILL.md +111 -0
package/templates/wrangler.toml +14 -0

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,27 @@
+# Changelog
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.1.0] - 2026-06-12
+Initial public release.
+### Added
+- `lazyanalytics` CLI: `setup`, `sites list/add/remove`, `snippet`, `skill install`,
+  `config`, plus query commands `stats`, `pages`, `referrers`, `geo`, `browsers`,
+  `timeseries`, and `usage`.
+- One-command deploy: `npx @jayfarei/lazyanalytics setup` scaffolds wrangler config into
+  `~/.config/lazyanalytics/`, deploys the prebundled worker to your Cloudflare
+  account, and generates/stores all secrets without printing them.
+- Cloudflare Worker with `/collect` beacon ingest, `/tracker.js`, authenticated
+  `/api/*` query endpoints (sampling-aware Analytics Engine SQL), `/api/sites`,
+  a built-in `/dashboard`, and `/health`.
+- Claude Code skill (`skill/SKILL.md`) covering the full lifecycle, installable
+  via `lazyanalytics skill install [--project]`.
+- Privacy design: salted daily-rotating visitor hashes (`HASH_SALT` secret),
+  no cookies, no raw IPs, query strings stripped, referrer domain only.
+  See PRIVACY.md.
+- Vitest suite for the worker and GitHub Actions CI.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Jay Farei
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,210 @@
+# lazyanalytics
+Agent-first, self-hosted web analytics on Cloudflare Workers + Analytics Engine.
+- **Self-hosted**: deploys into *your* Cloudflare account. Your traffic data never leaves it.
+- **Agent-first**: a CLI that returns JSON by default, with semantic exit codes and `--help` text written for AI agents. Ships a Claude Code skill.
+- **Privacy-respecting**: no cookies, no fingerprinting, no raw IPs, no query strings. See [PRIVACY.md](PRIVACY.md).
+- **Cheap**: a small site fits comfortably in the Cloudflare free tier (`lazyanalytics usage` shows your headroom).
+## Quick start
+```bash
+# 1. Deploy the worker into your Cloudflare account
+CLOUDFLARE_API_TOKEN=<token> npx @jayfarei/lazyanalytics setup \
+  --sites example.com --account-id <32-hex-account-id>
+# 2. Add the printed snippet to each site's <head>
+# 3. Query
+npx @jayfarei/lazyanalytics stats --site example.com --period 7d
+```
+`setup` is interactive if you omit flags, and non-interactive with `--yes`. It scaffolds `~/.config/lazyanalytics/worker/`, deploys via `wrangler`, generates `API_SECRET` and `HASH_SALT` (never printed), sets the worker secrets (including `CF_ACCOUNT_ID`/`CF_API_TOKEN`, which Analytics Engine reads require — see [Secrets model](#secrets-model)), writes `~/.config/lazyanalytics/.env` (mode 0600), health-checks the deployment, and prints the tracking snippet per site. Re-running is idempotent; pass `--rotate-secrets` to regenerate credentials.
+By default the token you give `setup` is also stored on the worker as `CF_API_TOKEN` for Analytics Engine reads. To keep the deploy-capable token off the worker, re-run with a token scoped to **Account Analytics: Read** only after the first deploy, or overwrite the secret manually:
+```bash
+cd ~/.config/lazyanalytics/worker
+echo "<read-only-token>" | CLOUDFLARE_API_TOKEN=<token> CLOUDFLARE_ACCOUNT_ID=<account-id> npx wrangler@4 secret put CF_API_TOKEN
+```
+## The tracking snippet
+```html
+<script defer id="analytics" data-site-id="example.com"
+  src="https://lazyanalytics.YOUR-SUBDOMAIN.workers.dev/tracker.js"></script>
+```
+The script is <2KB, sets no cookies, strips query strings and fragments in the browser, sends only the referrer *domain*, and tracks SPA navigations. `data-site-id` must match a site in the worker's `ALLOWED_SITES`. Print snippets anytime with `lazyanalytics snippet [--site example.com]`.
+## CLI reference
+Install globally (`npm i -g @jayfarei/lazyanalytics`) or use `npx @jayfarei/lazyanalytics`.
+### Lifecycle commands
+| Command | What it does |
+| ------- | ------------ |
+| `setup` | Deploy the worker and configure the CLI. Flags: `--sites <csv>`, `--account-id <id>`, `--name <worker-name>` (default `lazyanalytics`), `--rotate-secrets`, `-y/--yes`. Needs `CLOUDFLARE_API_TOKEN` (env or hidden prompt). |
+| `sites list` | List tracked sites via the worker's `/api/sites` endpoint. |
+| `sites add <domain>` | Add a site to `ALLOWED_SITES` in the scaffolded `wrangler.toml` and redeploy. Needs `CLOUDFLARE_API_TOKEN`. |
+| `sites remove <domain>` | Remove a site and redeploy (refuses to remove the last site). |
+| `snippet [--site X]` | Print the tracking `<script>` tag for one site, or all tracked sites. |
+| `skill install [--project]` | Install the Claude Code skill to `~/.claude/skills/lazyanalytics/` (or `./.claude/skills/lazyanalytics/` with `--project`). |
+| `config path` / `config get <key>` / `config set <key> <value>` | Inspect/edit `~/.config/lazyanalytics/.env`. Sensitive values (`TOKEN`/`SECRET`/`SALT`/`PASSWORD`) are masked on `get`. |
+| `usage` | Worker request usage, free-plan headroom, and cost estimate via the Cloudflare GraphQL API. Flags: `-p today\|7d\|30d`, `-w/--worker <name>`. Needs `CF_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN`. |
+### Query commands
+```bash
+lazyanalytics stats      --site example.com --period 7d
+lazyanalytics pages      --site example.com --period 30d --limit 5
+lazyanalytics referrers  --site example.com
+lazyanalytics geo        --site example.com --period 30d
+lazyanalytics browsers   --site example.com --type os        # browser | os | device
+lazyanalytics timeseries --site example.com --unit day       # hour | day
+```
+| Flag | Short | Default | Description |
+| ---- | ----- | ------- | ----------- |
+| `--site` | `-s` | required | Site to query |
+| `--period` | `-p` | `7d` | `1d` to `90d` |
+| `--limit` | `-l` | `10` | Max results (1-100) |
+| `--json` | | default | JSON output (for agents) |
+| `--table` | | | Human-readable table |
+Exit codes: `0` data returned, `1` error, `2` success but empty, `3` config/auth error.
+## HTTP API reference
+All `/api/*` endpoints require `Authorization: Bearer <API_SECRET>` (constant-time compared). Responses use the envelope `{ "data": ..., "meta": { "site", "period", "sampled" } }`; `sampled` is true only when Analytics Engine actually sampled the underlying rows.
+| Endpoint | Auth | Description |
+| -------- | ---- | ----------- |
+| `GET /api/stats` | yes | Pageviews, approximate daily visitors, avg screen width. Params: `site` (required), `period`. |
+| `GET /api/pages` | yes | Top pages. Params: `site`, `period`, `limit`. |
+| `GET /api/referrers` | yes | Top external referrer domains. Params: `site`, `period`, `limit`. |
+| `GET /api/geo` | yes | Country breakdown. Params: `site`, `period`, `limit`. |
+| `GET /api/browsers` | yes | Browser/OS/device breakdown. Params: `site`, `period`, `limit`, `type` (`browser`\|`os`\|`device`). |
+| `GET /api/timeseries` | yes | Pageviews over time. Params: `site`, `period`, `unit` (`hour`\|`day`). |
+| `GET /api/sites` | yes | Tracked sites: `{ "data": [{"site": "example.com"}], "meta": {"count": 1} }`. |
+| `POST /collect` | no | Beacon ingest. Body: `{ "sid", "url", "ref?", "sw?", "us?", "um?" }`. Returns 204. Bots get 204 but are not recorded; beacons are dropped (204) if the worker has no `ALLOWED_SITES` or `HASH_SALT` configured; unknown `sid` returns 400. CORS-enabled. |
+| `GET /tracker.js` | no | Serves the tracking script. |
+| `GET /dashboard` | no (page) | Built-in dashboard UI. The page is public, but data loads only after you enter the API token in-page; the token is kept in `sessionStorage` (cleared when the tab closes). You can hand off a session via `https://.../dashboard#token=<API_SECRET>`; the fragment is consumed and immediately stripped from the URL. |
+| `GET /health` | no | `{ "status": "ok", "version": "0.1.0", "timestamp": "..." }`. |
+Example:
+```bash
+curl -H "Authorization: Bearer $ANALYTICS_API_TOKEN" \
+  "https://lazyanalytics.YOUR-SUBDOMAIN.workers.dev/api/stats?site=example.com&period=7d"
+```
+## Architecture
+```
+  Your sites (example.com, blog.example.com, ...)
+        │  <script data-site-id="..." src=".../tracker.js">
+        │
+        ▼  beacon POST to /collect
+  ┌──────────────────────────────────────┐
+  │   Cloudflare Worker (your account)   │
+  │                                      │
+  │  /tracker.js   serves tracking JS    │
+  │  /collect      ingests pageviews     │
+  │  /api/*        query endpoints       │
+  │  /dashboard    built-in UI           │
+  │  /health       health check          │
+  └──────────┬───────────────────────────┘
+             │  writeDataPoint() / SQL API
+  ┌──────────▼───────────────────────────┐
+  │     Cloudflare Analytics Engine      │
+  │     (ClickHouse-backed, 90-day)      │
+  └──────────────────────────────────────┘
+        ▲
+        │  HTTPS + bearer token
+  ┌─────┴──────────────────┐
+  │   lazyanalytics CLI    │  → JSON for agents, --table for humans
+  │  (or any HTTP client)  │  → Claude Code skill, cron reports, alerting
+  └────────────────────────┘
+```
+1. **Collection**: the tracker sends a beacon on page load and SPA navigations with the page URL (already stripped), referrer domain, screen width, and UTM source/medium.
+2. **Processing**: the worker filters bots, parses the UA, computes a salted daily visitor hash, and writes one data point to Analytics Engine.
+3. **Querying**: `/api/*` translates HTTP params into sampling-aware SQL (`SUM(_sample_interval)`, never `COUNT(*)`).
+## Data model
+One Analytics Engine data point per pageview:
+| Field | Contents | Example |
+| ----- | -------- | ------- |
+| `index1` | Visitor hash: SHA-256 of `site\|ip\|ua\|date\|HASH_SALT`, truncated to 32 hex chars | `a3f8c9...` |
+| `blob1` | Site ID | `example.com` |
+| `blob2` | Page path (no query string) | `/blog/my-post` |
+| `blob3` | Referrer domain (external only) | `google.com` |
+| `blob4` | Country code (`CF-IPCountry`) | `US` |
+| `blob5` / `blob6` / `blob7` | Browser / OS / device | `Chrome` / `macOS` / `desktop` |
+| `blob8` / `blob9` | UTM source / medium | `twitter` / `social` |
+| `double1` | Count (always 1) | `1` |
+| `double2` | Screen width | `1440` |
+**Sampling note**: Analytics Engine downsamples high-volume data. All queries use `SUM(_sample_interval)` for correct estimates, and `meta.sampled` tells you when an answer is an estimate rather than an exact count. Data is retained for 90 days.
+## Privacy
+No cookies, no fingerprinting, no cross-site tracking. Raw IPs and user agents are only hashed transiently (with a per-deployment secret salt, rotated into the hash daily) and never stored. URLs are stripped of query strings client-side; referrers are reduced to a domain. Full details, including honest caveats about hash reversibility, in [PRIVACY.md](PRIVACY.md).
+## Secrets model
+| Secret | Lives where | Purpose |
+| ------ | ----------- | ------- |
+| `API_SECRET` | Worker secret + `~/.config/lazyanalytics/.env` (as `ANALYTICS_API_TOKEN`) | Bearer token for `/api/*` and the dashboard |
+| `HASH_SALT` | Worker secret + CLI config (so re-runs keep hashes stable) | Salts visitor hashes; never printed |
+| `CLOUDFLARE_API_TOKEN` | Your shell env only, at deploy time | Used by `setup` / `sites add\|remove` / `usage`. Never stored by the CLI, never sent to the worker |
+| `CF_ACCOUNT_ID` / `CF_API_TOKEN` | Worker secrets (set by `setup`) | Used by worker-side `/api/*` queries (Analytics Engine reads go through Cloudflare's REST API) |
+Guidance:
+- The CLI config file is written with mode `0600`. `config get` masks sensitive values.
+- Use a **least-privilege deploy token**: `Workers Scripts: Edit` + `Account Analytics: Read`. Treat it as setup-time only; the deploy token itself is never stored on the worker.
+- `setup` stores the token it was given as the worker-side `CF_API_TOKEN`. For least privilege, give it (or later overwrite the secret with) a *separate* token scoped to `Account Analytics: Read` only, so a worker compromise cannot touch your Workers.
+- The analytics bearer token (`API_SECRET`) can only read analytics; it has no power over your Cloudflare account.
+## Development
+```bash
+git clone https://github.com/JayFarei/lazyanalytics.git
+cd lazyanalytics
+npm install            # installs worker/ and cli/ workspaces
+npm run build          # esbuild-bundles dist/worker.js + compiles cli/dist
+npm test               # vitest (worker workspace)
+# Run the worker locally
+cd worker
+cat > .dev.vars <<'EOF'
+API_SECRET=dev-secret
+HASH_SALT=dev-salt
+EOF
+npx wrangler dev       # ALLOWED_SITES comes from worker/wrangler.toml [vars]
+# Run the CLI from source
+npx tsx cli/src/index.ts stats --site example.com
+```
+The npm package ships `cli/dist/`, the prebundled `dist/worker.js`, `templates/wrangler.toml`, and `skill/SKILL.md`; the `worker/` source is only used for development.
+### Advanced: credential proxies
+The repo contains a `cli/bin/analytics` bash wrapper that routes requests through a OneCLI credential proxy. It is experimental, unsupported, and not part of the npm package. Direct mode (`ANALYTICS_API_URL` + `ANALYTICS_API_TOKEN`) is the supported path.
+## Limitations
+- 90-day retention (Analytics Engine), no per-visitor deletion.
+- Visitor counts are approximations (NAT/VPN undercounts, shared devices overcount).
+- No bounce rate or session duration (Analytics Engine has no JOINs).
+- Data points can take seconds to minutes to become queryable.
+## Contributing & license
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) for how to report vulnerabilities. MIT licensed, see [LICENSE](LICENSE).

package/cli/dist/commands/base.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { Command } from 'commander';
2	+ export declare function makeCommand(name: string, description: string): Command;

package/cli/dist/commands/base.js ADDED Viewed

@@ -0,0 +1,129 @@
+import { Command } from 'commander';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import tls from 'node:tls';
+import { loadEnv } from '../lib/env.js';
+// Advanced/experimental: trust an extra proxy CA cert at runtime.
+// Opt-in only via ANALYTICS_PROXY_CA=<path> — never loaded implicitly from
+// the working directory. NODE_EXTRA_CA_CERTS must be set before Node boots,
+// so we patch the secure context here instead.
+function loadProxyCA(path) {
+    if (!existsSync(path))
+        return;
+    try {
+        const cert = readFileSync(path, 'utf-8');
+        const origCreateSecureContext = tls.createSecureContext;
+        tls.createSecureContext = function (options = {}) {
+            const ctx = origCreateSecureContext.call(this, options);
+            ctx.context.addCACert(cert);
+            return ctx;
+        };
+    }
+    catch { /* ignore */ }
+}
+if (process.env.HTTPS_PROXY && process.env.ANALYTICS_PROXY_CA) {
+    loadProxyCA(resolve(process.env.ANALYTICS_PROXY_CA));
+}
+function getConfig() {
+    loadEnv();
+    const apiUrl = process.env.ANALYTICS_API_URL;
+    const apiToken = process.env.ANALYTICS_API_TOKEN;
+    const proxyMode = !!process.env.HTTPS_PROXY;
+    if (!apiUrl) {
+        console.error('Error: ANALYTICS_API_URL is not configured.');
+        console.error('Example: https://lazyanalytics.YOUR-SUBDOMAIN.workers.dev');
+        console.error('');
+        console.error('Run "lazyanalytics setup" to deploy and configure, or set');
+        console.error('ANALYTICS_API_URL and ANALYTICS_API_TOKEN in the environment.');
+        process.exit(3);
+    }
+    // In proxy mode (HTTPS_PROXY set), the proxy injects the Authorization header.
+    if (!apiToken && !proxyMode) {
+        console.error('Error: No authentication configured.');
+        console.error('');
+        console.error('Set ANALYTICS_API_TOKEN in the environment, or run');
+        console.error('"lazyanalytics setup" to write it to ~/.config/lazyanalytics/.env.');
+        process.exit(3);
+    }
+    return { apiUrl: apiUrl.replace(/\/$/, ''), apiToken: apiToken || '', proxyMode };
+}
+async function fetchApi(endpoint, params) {
+    const { apiUrl, apiToken, proxyMode } = getConfig();
+    const url = new URL(`${apiUrl}/api/${endpoint}`);
+    for (const [k, v] of Object.entries(params)) {
+        if (v)
+            url.searchParams.set(k, v);
+    }
+    // In proxy mode, the credential proxy injects the Authorization header.
+    // In direct mode, we add it ourselves.
+    const headers = {};
+    if (!proxyMode && apiToken) {
+        headers.Authorization = `Bearer ${apiToken}`;
+    }
+    const response = await fetch(url.toString(), { headers });
+    if (response.status === 401) {
+        console.error('Error: Authentication failed. Check your ANALYTICS_API_TOKEN.');
+        process.exit(3);
+    }
+    if (!response.ok) {
+        const body = await response.text();
+        console.error(`Error: API returned ${response.status}: ${body}`);
+        process.exit(1);
+    }
+    return response.json();
+}
+function formatTable(data) {
+    if (data.length === 0)
+        return '(no data)';
+    const keys = Object.keys(data[0]);
+    const widths = keys.map((k) => Math.max(k.length, ...data.map((row) => String(row[k] ?? '').length)));
+    const header = keys.map((k, i) => k.padEnd(widths[i])).join('  ');
+    const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+    const rows = data.map((row) => keys.map((k, i) => String(row[k] ?? '').padEnd(widths[i])).join('  '));
+    return [header, sep, ...rows].join('\n');
+}
+export function makeCommand(name, description) {
+    const cmd = new Command(name);
+    cmd
+        .description(description)
+        .requiredOption('-s, --site <site>', 'Site to query (e.g., example.com)')
+        .option('-p, --period <period>', 'Time period (e.g., 7d, 30d)', '7d')
+        .option('-l, --limit <limit>', 'Max results to return', '10')
+        .option('--json', 'Output as JSON (default)', true)
+        .option('--table', 'Output as human-readable table')
+        .action(async (opts) => {
+        try {
+            const params = {
+                site: opts.site,
+                period: opts.period,
+                limit: opts.limit,
+            };
+            // Add extra params from the command (type, unit)
+            if (opts.type)
+                params.type = opts.type;
+            if (opts.unit)
+                params.unit = opts.unit;
+            const result = await fetchApi(name, params);
+            if (opts.table) {
+                const arr = Array.isArray(result.data) ? result.data : [result.data];
+                console.log(formatTable(arr));
+                if (result.meta.sampled) {
+                    console.log('\n(data may be sampled)');
+                }
+            }
+            else {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            // Exit code 2 if no data
+            const dataArr = Array.isArray(result.data) ? result.data : [result.data];
+            const isEmpty = dataArr.length === 0 || (dataArr.length === 1 && Object.values(dataArr[0]).every((v) => v === 0 || v === null));
+            if (isEmpty)
+                process.exit(2);
+        }
+        catch (e) {
+            console.error(`Error: ${e instanceof Error ? e.message : 'Unknown error'}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}

package/cli/dist/commands/config.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { Command } from 'commander';
2	+ export declare function configCommand(): Command;

package/cli/dist/commands/config.js ADDED Viewed

@@ -0,0 +1,45 @@
+import { Command } from 'commander';
+import { CONFIG_ENV_PATH, readEnvFile, writeEnvFile } from '../lib/env.js';
+/** Keys whose values must never be printed in full. */
+const SENSITIVE_KEY = /TOKEN|SECRET|SALT|PASSWORD/i;
+function maskValue(value) {
+    if (value.length <= 4)
+        return '****';
+    return '****' + value.slice(-4);
+}
+export function configCommand() {
+    const cmd = new Command('config');
+    cmd.description(`Inspect and edit the CLI config file (${CONFIG_ENV_PATH})`);
+    cmd
+        .command('path')
+        .description('Print the config file path')
+        .action(() => {
+        console.log(CONFIG_ENV_PATH);
+    });
+    cmd
+        .command('get <key>')
+        .description('Print a config value (sensitive values are masked)')
+        .action((key) => {
+        const vars = readEnvFile(CONFIG_ENV_PATH);
+        if (!(key in vars)) {
+            console.error(`Error: ${key} is not set in ${CONFIG_ENV_PATH}`);
+            process.exit(2);
+        }
+        const value = vars[key];
+        console.log(SENSITIVE_KEY.test(key) ? maskValue(value) : value);
+    });
+    cmd
+        .command('set <key> <value>')
+        .description('Set a config value (file is written with mode 0600)')
+        .action((key, value) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            console.error(`Error: invalid key "${key}" (use letters, digits, underscores)`);
+            process.exit(1);
+        }
+        const vars = readEnvFile(CONFIG_ENV_PATH);
+        vars[key] = value;
+        writeEnvFile(CONFIG_ENV_PATH, vars);
+        console.log(`Set ${key} in ${CONFIG_ENV_PATH}`);
+    });
+    return cmd;
+}

package/cli/dist/commands/setup.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { Command } from 'commander';
2	+ export declare function setupCommand(): Command;

package/cli/dist/commands/setup.js ADDED Viewed

@@ -0,0 +1,155 @@
+import { Command } from 'commander';
+import { randomBytes } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONFIG_ENV_PATH, WORKER_SCAFFOLD_DIR, loadEnv, readEnvFile, writeEnvFile, } from '../lib/env.js';
+import { packagedWorkerBundle, packagedWranglerTemplate } from '../lib/paths.js';
+import { isValidDomain, prompt, promptHidden, trackingSnippet } from '../lib/prompt.js';
+import { readAllowedSites } from '../lib/scaffold.js';
+import { parseWorkersDevUrl, wranglerDeploy, wranglerSecretPut } from '../lib/wrangler.js';
+function fail(message) {
+    console.error(`Error: ${message}`);
+    // Exit 3 = missing/invalid configuration, matching the other commands.
+    process.exit(3);
+}
+function parseSites(raw) {
+    const sites = raw
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    if (sites.length === 0)
+        fail('At least one site is required');
+    for (const site of sites) {
+        if (!isValidDomain(site)) {
+            fail(`Invalid site domain: "${site}" (expected a bare domain like example.com)`);
+        }
+    }
+    return [...new Set(sites)];
+}
+export function setupCommand() {
+    const cmd = new Command('setup');
+    cmd
+        .description('Deploy the analytics worker to your Cloudflare account and configure the CLI. ' +
+        'Requires CLOUDFLARE_API_TOKEN (env) and a Cloudflare account ID. ' +
+        'Idempotent: re-running reuses existing secrets unless --rotate-secrets is passed.')
+        .option('--sites <sites>', 'Comma-separated list of site domains to track')
+        .option('--account-id <id>', 'Cloudflare account ID (32-char hex)')
+        .option('--name <name>', 'Worker name', 'lazyanalytics')
+        .option('--rotate-secrets', 'Regenerate API_SECRET and HASH_SALT instead of reusing them')
+        .option('-y, --yes', 'Non-interactive mode: never prompt, fail if input is missing')
+        .action(async (opts) => {
+        loadEnv();
+        const nonInteractive = !!opts.yes;
+        // --- Cloudflare API token (env only, optionally prompted; never printed) ---
+        let apiToken = process.env.CLOUDFLARE_API_TOKEN || '';
+        if (!apiToken) {
+            if (nonInteractive) {
+                fail('CLOUDFLARE_API_TOKEN env var is required (create one at dash.cloudflare.com with Workers Scripts:Edit + Account Analytics:Read)');
+            }
+            apiToken = await promptHidden('Cloudflare API token (input hidden): ');
+            if (!apiToken)
+                fail('A Cloudflare API token is required');
+        }
+        // --- Account ID ---
+        let accountId = opts.accountId || process.env.CF_ACCOUNT_ID || process.env.CLOUDFLARE_ACCOUNT_ID || '';
+        if (!accountId) {
+            if (nonInteractive)
+                fail('Account ID required: pass --account-id or set CF_ACCOUNT_ID');
+            accountId = await prompt('Cloudflare account ID (dash.cloudflare.com > Workers & Pages sidebar): ');
+        }
+        if (!/^[a-f0-9]{32}$/i.test(accountId)) {
+            fail('Account ID must be a 32-character hex string');
+        }
+        // --- Sites (flag > existing scaffold > prompt) ---
+        const wranglerTomlPath = join(WORKER_SCAFFOLD_DIR, 'wrangler.toml');
+        let sitesRaw = opts.sites || '';
+        if (!sitesRaw) {
+            const existing = readAllowedSites(wranglerTomlPath);
+            if (existing.length > 0) {
+                sitesRaw = existing.join(',');
+                console.log(`Reusing existing site list: ${sitesRaw}`);
+            }
+        }
+        if (!sitesRaw) {
+            if (nonInteractive)
+                fail('Site list required: pass --sites example.com,blog.example.com');
+            sitesRaw = await prompt('Sites to track (comma-separated, e.g. mysite.com,blog.example.com): ');
+        }
+        const sites = parseSites(sitesRaw);
+        // --- Scaffold ~/.config/lazyanalytics/worker/ ---
+        mkdirSync(WORKER_SCAFFOLD_DIR, { recursive: true });
+        const bundlePath = packagedWorkerBundle();
+        if (!existsSync(bundlePath)) {
+            fail(`Worker bundle not found at ${bundlePath}. ` +
+                'If running from a repo clone, run "npm run build" at the repo root first.');
+        }
+        copyFileSync(bundlePath, join(WORKER_SCAFFOLD_DIR, 'worker.js'));
+        const templatePath = packagedWranglerTemplate();
+        if (!existsSync(templatePath))
+            fail(`wrangler.toml template not found at ${templatePath}`);
+        const toml = readFileSync(templatePath, 'utf-8')
+            .replace(/__WORKER_NAME__/g, opts.name)
+            .replace(/__ALLOWED_SITES__/g, sites.join(','));
+        writeFileSync(wranglerTomlPath, toml);
+        console.log(`Scaffolded worker in ${WORKER_SCAFFOLD_DIR}`);
+        // --- Deploy ---
+        const wranglerEnv = { CLOUDFLARE_API_TOKEN: apiToken, CLOUDFLARE_ACCOUNT_ID: accountId };
+        console.log('\nDeploying worker with wrangler...');
+        const deployOutput = await wranglerDeploy(WORKER_SCAFFOLD_DIR, wranglerEnv);
+        let workerUrl = parseWorkersDevUrl(deployOutput);
+        if (!workerUrl) {
+            console.error('\nError: could not parse the workers.dev URL from wrangler output.');
+            if (nonInteractive) {
+                fail('Re-run interactively, or check "npx wrangler deployments list" for the URL');
+            }
+            const entered = await prompt('Paste the deployed worker URL (https://...workers.dev): ');
+            if (!/^https:\/\/.+/.test(entered))
+                fail('A valid https:// worker URL is required');
+            workerUrl = entered.replace(/\/$/, '');
+        }
+        // --- Secrets (reused across runs unless --rotate-secrets) ---
+        const existingConfig = readEnvFile(CONFIG_ENV_PATH);
+        const rotate = !!opts.rotateSecrets;
+        const apiSecret = !rotate && existingConfig.ANALYTICS_API_TOKEN
+            ? existingConfig.ANALYTICS_API_TOKEN
+            : randomBytes(32).toString('hex');
+        const hashSalt = !rotate && existingConfig.HASH_SALT
+            ? existingConfig.HASH_SALT
+            : randomBytes(32).toString('hex');
+        console.log('\nSetting worker secrets (values are never printed)...');
+        await wranglerSecretPut(WORKER_SCAFFOLD_DIR, wranglerEnv, 'API_SECRET', apiSecret);
+        await wranglerSecretPut(WORKER_SCAFFOLD_DIR, wranglerEnv, 'HASH_SALT', hashSalt);
+        // The /api/* query endpoints read Analytics Engine through Cloudflare's
+        // SQL REST API, which needs account credentials on the worker. A token
+        // with Account Analytics:Read suffices; pass a narrower token here via
+        // setup if you don't want the deploy token stored on the worker.
+        await wranglerSecretPut(WORKER_SCAFFOLD_DIR, wranglerEnv, 'CF_ACCOUNT_ID', accountId);
+        await wranglerSecretPut(WORKER_SCAFFOLD_DIR, wranglerEnv, 'CF_API_TOKEN', apiToken);
+        // --- Persist CLI config (0600) ---
+        writeEnvFile(CONFIG_ENV_PATH, {
+            ...existingConfig,
+            ANALYTICS_API_URL: workerUrl,
+            ANALYTICS_API_TOKEN: apiSecret,
+            CF_ACCOUNT_ID: accountId,
+            HASH_SALT: hashSalt,
+        });
+        console.log(`Config written to ${CONFIG_ENV_PATH} (mode 0600)`);
+        // --- Health check ---
+        try {
+            const res = await fetch(`${workerUrl}/health`);
+            console.log(`\nHealth check: ${res.ok ? 'ok' : `failed (HTTP ${res.status})`}`);
+        }
+        catch (e) {
+            console.log(`\nHealth check: unreachable (${e instanceof Error ? e.message : 'unknown error'}). ` +
+                'The worker may take a few seconds to become available.');
+        }
+        // --- Tracking snippets ---
+        console.log('\nSetup complete. Add this snippet to each site:');
+        for (const site of sites) {
+            console.log(`\n  ${site}:`);
+            console.log(`    ${trackingSnippet(workerUrl, site)}`);
+        }
+        console.log('\nThen query with: lazyanalytics stats --site ' + sites[0]);
+    });
+    return cmd;
+}

package/cli/dist/commands/sites.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { Command } from 'commander';
2	+ export declare function sitesCommand(): Command;