feat: anonymous opt-out telemetry (PostHog) (#74)

* feat: anonymous opt-out telemetry (PostHog)

Add a thin telemetry layer that counts command usage anonymously. All
PostHog-specific code lives behind src/telemetry/index.ts so the backend
can be swapped in one file.

- Whitelist payload only: machine_id, scaffold_id, command name, mex_version,
  os, node_version. No args, paths, file contents, repo names, IP, or geo
  (disableGeoip is set so PostHog never derives location from the IP).
- Opt-out precedence: DO_NOT_TRACK=1, MEX_TELEMETRY=0, `mex config set
  telemetry off`, else on. Dev-repo guard hard-disables when run from a clone
  of mex itself, before any disk read.
- machine_id is a random UUID at ~/.mex/telemetry-id (0600), created only when
  enabled. scaffold_id (from E1) is passed as a string only — never the
  identity object — so scaffold_name/origin/upstream can't leak.
- Fire-and-forget: capture fires in a preAction hook (so process.exit commands
  like `check` on drift are still counted); flush is best-effort and bounded;
  a telemetry failure never blocks or changes a command's exit code.
- Transparency: `mex telemetry inspect` prints the exact would-be payload
  without sending (and without minting the machine-id file); `mex telemetry
  status` shows enabled/disabled + reason; one-time first-run notice to stderr.
- Tests never emit real events (vitest sets MEX_TELEMETRY=0).
- Docs: TELEMETRY.md + README link + CHANGELOG entry.

* fix(telemetry): address review on #74

- preAction no longer fires for the telemetry/config meta-commands, so
  `mex telemetry inspect` sends no event and never creates the machine-id
  file — it stays a pure audit surface even when telemetry is enabled.
- flush() now clears its race timer in a finally, so a fast flush can't
  leave an 800ms timeout pending and delay process exit.
- Remove unused `constants` import in global-config.ts.
- Fix isDevRepo JSDoc: the bare `mex` package name is intentionally excluded.
- Make the "no I/O at import time" test real — it now re-evaluates the module
  under a fresh HOME and asserts nothing is written, instead of passing
  vacuously.
- TELEMETRY.md: drop the non-interactive auto-disable claim; CI usage is
  counted (no TTY gate), so the doc matches the code.

Author: theDakshJaitly

CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- **Anonymous telemetry** — opt-out usage counting via PostHog. Each command sends one event with only `machine_id`, `scaffold_id`, `command` name, `mex_version`, `os`, and `node_version` — no args, paths, file contents, repo names, IP, or location. Opt out with `DO_NOT_TRACK=1`, `MEX_TELEMETRY=0`, or `mex config set telemetry off`. Audit the exact payload with `mex telemetry inspect`; check state with `mex telemetry status`. Telemetry is disabled automatically when running from a clone of the mex repo. See [TELEMETRY.md](TELEMETRY.md).
 - **Scaffold identity** — `.mex/config.json` now carries a stable `scaffold_id` (UUID v4), `scaffold_name`, and nullable `origin`/`upstream`. Generated at `mex setup` and silently backfilled for existing scaffolds on the next CLI invocation. New `getScaffoldIdentity()` export on the public API.
 - **broken-link drift checker** — flags Markdown links in scaffold files whose local target file does not exist.
 

README.md

@@ -262,6 +262,10 @@ Optional settings live in `.mex/config.json`. Missing values fall back to defaul
 }
 ```
 
+## Telemetry
+
+mex collects anonymous, opt-out usage data (command name, version, OS — never paths, args, file contents, IP, or personal data) to understand how the tool is used. Audit the exact payload with `mex telemetry inspect`, and opt out any time with `DO_NOT_TRACK=1`, `MEX_TELEMETRY=0`, or `mex config set telemetry off`. Full details: [TELEMETRY.md](TELEMETRY.md).
+
 ## Ecosystem
 
 mex is provider-neutral. Integration guides, sponsored examples, and community recipes should be useful on their own, clearly labeled, and live in docs rather than silently changing the default experience.

TELEMETRY.md

@@ -0,0 +1,94 @@
+# Telemetry
+
+mex collects **anonymous, opt-out** usage data so the maintainer can see how the
+tool is actually used — which commands matter, roughly how many people use it,
+and whether a project is used by a team. That's the entire purpose. There is no
+advertising, no profiling, and no way to tie any data back to a person.
+
+If you'd rather send nothing, see [How to opt out](#how-to-opt-out) — it's one
+command or one environment variable.
+
+## What is collected
+
+Every time you run a `mex` command, **one** event is sent containing **exactly**
+these fields and nothing else:
+
+| Field | Example | What it is |
+|-------|---------|------------|
+| `machine_id` | `3f2a…` (random UUID) | A random ID generated once per machine. Not your username, hostname, or anything derived from you. |
+| `scaffold_id` | `9b1c…` (random UUID) | A random ID for the mex scaffold (project). Only present when you run inside a scaffold. Lets us tell "one team on one project" apart from "one person on many machines." |
+| `command` | `check` | The command **name only** — e.g. `check`, `sync`, `log`. |
+| `mex_version` | `0.5.1` | The installed mex version. |
+| `os` | `darwin` | The platform string (`darwin` / `linux` / `win32`). |
+| `node_version` | `v22.17.1` | The Node.js version. |
+
+You can see the literal payload that would be sent, at any time, without sending
+anything:
+
+```bash
+mex telemetry inspect
+```
+
+## What is NEVER collected
+
+- **No personal data** — no name, email, username, hostname, or git identity.
+- **No IP address or location** — geolocation is explicitly disabled.
+- **No command arguments, flags, or paths.**
+- **No file names or file contents.**
+- **No repository name or git remote URL.**
+
+`machine_id` and `scaffold_id` are random UUIDs. They are **not** derived from
+your path, repo, email, or anything identifying — they are just random numbers
+that let counts be de-duplicated.
+
+## Where the data goes
+
+[PostHog](https://posthog.com) Cloud, **US region** (`https://us.i.posthog.com`).
+The ingestion key embedded in mex is write-only — it can send events but cannot
+read any data back.
+
+## When telemetry does NOT run
+
+Telemetry is automatically disabled — no event sent, no ID file created — when:
+
+- any opt-out below is active, **or**
+- mex is run from a clone of the mex repository itself (so the maintainer's own
+  development never pollutes the data).
+
+A telemetry failure (offline, firewall, ad-blocker) never blocks, slows, or
+changes the exit code of any command. It is fire-and-forget and fully ignored on
+error.
+
+## How to opt out
+
+Any **one** of these turns telemetry off completely. When off, no event is ever
+sent and the machine-id file is never created.
+
+| Method | Scope |
+|--------|-------|
+| `DO_NOT_TRACK=1` | The industry-standard env var. Honored everywhere. |
+| `MEX_TELEMETRY=0` | mex-specific env var. |
+| `mex config set telemetry off` | Persisted in `~/.mex/config.json` (per-machine). Re-enable with `mex config set telemetry on`. |
+
+Check the current state and the active opt-out reason any time:
+
+```bash
+mex telemetry status
+```
+
+## Files mex writes for telemetry
+
+- `~/.mex/telemetry-id` — your random `machine_id` (mode `0600`). Created only
+  when telemetry is enabled. Delete it any time; a new one is generated on the
+  next enabled run.
+- `~/.mex/config.json` — your global preferences, including the telemetry
+  opt-out flag.
+
+These are separate from a project's `.mex/config.json`, which holds the
+project's `scaffold_id`.
+
+## A note on PostHog metadata
+
+The PostHog client library attaches two of its own fields to each event —
+`$lib` (`posthog-node`) and `$lib_version`. These describe the sending library,
+not you, and contain no personal or usage data.

package-lock.json

@@ -56,6 +56,7 @@
     "commander": "^13.1.0",
     "glob": "^11.0.1",
     "ink": "^7.0.3",
+    "posthog-node": "^5.21.2",
     "react": "^19.2.6",
     "remark-frontmatter": "^5.0.0",
     "remark-parse": "^11.0.0",

package.json

@@ -2,9 +2,11 @@ import chalk from "chalk";
 import { Command, InvalidArgumentError } from "commander";
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
-import { findConfig, getScaffoldIdentity } from "./config.js";
+import { findConfig, getScaffoldIdentity, readScaffoldId } from "./config.js";
 import { reportConsole, reportQuiet, reportJSON, reportVerbose } from "./reporter.js";
 import { VERSION } from "./version.js";
+import { captureCommand, flush, isEnabled, getPayloadPreview, showFirstRunNotice } from "./telemetry/index.js";
+import { readMachineId, setGlobalConfigKey } from "./global-config.js";
 
 /**
  * Load config for a CLI command and backfill scaffold identity on the way.
@@ -41,6 +43,45 @@ async function runTuiCommand(): Promise<void> {
   launchTui();
 }
 
+// ── Telemetry hooks ──
+
+// preAction: fire the event at the START of the command. Two reasons:
+//  - the async request gets the whole command runtime to land in the background
+//  - commands that call process.exit() (e.g. `check` on drift) are still
+//    counted; a postAction hook would never run after process.exit and would
+//    systematically miss every error/drift outcome.
+// scaffold_id is resolved read-only (never mints). Telemetry never throws here.
+program.hook("preAction", (_thisCommand, actionCommand) => {
+  try {
+    // Never count the telemetry/config meta-commands. In particular,
+    // `telemetry inspect` must have zero side effects — no event sent, no
+    // machine-id file created — so it stays a pure audit surface.
+    const parentName = actionCommand.parent?.name();
+    if (parentName === "telemetry" || parentName === "config") return;
+
+    let scaffoldId: string | undefined;
+    try {
+      scaffoldId = readScaffoldId(findConfig().scaffoldRoot);
+    } catch {
+      // No scaffold (or not in one) — omit scaffold_id.
+    }
+    captureCommand(actionCommand.name(), scaffoldId);
+  } catch {
+    // Telemetry must never affect command behaviour.
+  }
+});
+
+// postAction: best-effort bounded flush for commands that exit naturally.
+// Commands that process.exit() skip this, but their event was already sent
+// from preAction (flushAt:1 fires the request immediately).
+program.hook("postAction", async () => {
+  try {
+    await flush();
+  } catch {
+    // Telemetry must never affect command behaviour.
+  }
+});
+
 program
   .name("mex")
   .description("CLI engine for mex scaffold — drift detection, pre-analysis, and targeted sync")
@@ -283,6 +324,74 @@ program
     }
   });
 
+// ── Telemetry ──
+const telemetryCmd = program
+  .command("telemetry")
+  .description("Telemetry transparency commands");
+
+telemetryCmd
+  .command("inspect")
+  .description("Print the exact JSON payload that would be sent (without sending it)")
+  .action(() => {
+    try {
+      // Read-only: use readScaffoldId (never mints), not getScaffoldIdentity
+      let scaffoldId: string | undefined;
+      try {
+        const config = findConfig();
+        scaffoldId = readScaffoldId(config.scaffoldRoot);
+      } catch { /* no scaffold — omit scaffold_id */ }
+
+      // Read-only: show the machine_id only if it already exists. Auditing the
+      // payload must never plant the tracking file on disk.
+      const machineId = readMachineId();
+
+      const payload = getPayloadPreview("inspect", scaffoldId, machineId);
+      console.log(JSON.stringify(payload, null, 2));
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
+telemetryCmd
+  .command("status")
+  .description("Show whether telemetry is enabled and the active opt-out reason")
+  .action(() => {
+    const result = isEnabled();
+    if (result.enabled) {
+      console.log("Telemetry: enabled");
+    } else {
+      console.log(`Telemetry: disabled (reason: ${result.reason})`);
+    }
+  });
+
+// ── Config ──
+const configCmd = program
+  .command("config")
+  .description("Manage global mex configuration");
+
+configCmd
+  .command("set <key> <value>")
+  .description("Set a global config value (e.g. telemetry on|off)")
+  .action((key: string, value: string) => {
+    try {
+      if (key === "telemetry") {
+        if (value !== "on" && value !== "off") {
+          console.error(`Invalid value "${value}" for telemetry. Use "on" or "off".`);
+          process.exit(1);
+        }
+        setGlobalConfigKey("telemetry", value);
+        console.log(`Telemetry set to "${value}" in ~/.mex/config.json`);
+      } else {
+        console.error(`Unknown config key "${key}". Supported keys: telemetry`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
 // ── Quick Reference ──
 program
   .command("commands")
@@ -309,15 +418,23 @@ program
     console.log("  mex watch              Install post-commit hook for auto drift score");
     console.log("  mex watch --interval   Run heartbeat every 30 minutes (or config value)");
     console.log("  mex watch --uninstall  Remove the post-commit hook");
+    console.log("  mex telemetry inspect  Show the exact telemetry payload (without sending)");
+    console.log("  mex telemetry status   Show telemetry enabled/disabled and reason");
+    console.log("  mex config set <k> <v> Set a global config value (e.g. telemetry off)");
     console.log();
     console.log(chalk.dim("Not installed globally? Replace 'mex' with 'npx mex-agent'."));
     console.log();
   });
 
 // Skip auto-parse when imported (e.g. by tests). The bin entry is built by
-// tsup as ./dist/cli.js with a shebang banner; only run program.parse() when
-// this module is the script being invoked. Resolve argv[1] so symlinked bins
-// (npm global, npx, node_modules/.bin) match import.meta.url.
+// tsup as ./dist/cli.js with a shebang banner; only run program.parseAsync()
+// when this module is the script being invoked. Resolve argv[1] so symlinked
+// bins (npm global, npx, node_modules/.bin) match import.meta.url.
+//
+// Critical: use parseAsync(), not parse(). Commander's sync parse() does not
+// await the promise chain built by hooks and async actions — preAction/
+// postAction hooks would silently never execute and telemetry events would
+// never flush.
 let isMainModule = false;
 if (process.argv[1]) {
   try {
@@ -327,13 +444,18 @@ if (process.argv[1]) {
   }
 }
 if (isMainModule) {
-  program.parse();
+  showFirstRunNotice();
+  program.parseAsync().catch((err: Error) => {
+    console.error(err.message);
+    process.exit(1);
+  });
 }
 
 function buildCompletion(shell: string): string {
   const commands = [
     "setup", "check", "init", "sync", "pattern", "log", "timeline",
     "heartbeat", "doctor", "watch", "tui", "commands", "completion",
+    "telemetry", "config",
   ];
   if (shell === "bash") {
     return `_mex_completion() {

src/cli.ts

@@ -314,3 +314,15 @@ function findScaffoldRoot(projectRoot: string): string | null {
 
   return null;
 }
+
+/**
+ * Read-only scaffold_id lookup. Returns the scaffold_id string if it exists
+ * in config.json, or `undefined` if not. **Never mints or writes anything.**
+ *
+ * Used by telemetry inspect to show the payload without side-effects.
+ */
+export function readScaffoldId(scaffoldRoot: string): string | undefined {
+  const raw = loadPersistedConfig(scaffoldRoot);
+  const identity = loadScaffoldIdentity(raw);
+  return identity?.scaffold_id;
+}