feat(cli): add opt-out anonymous telemetry via PostHog

packages/cli/src/cli.ts

@@ -2,26 +2,70 @@
 
 import { defineCommand, runMain } from "citty";
 import { VERSION } from "./version.js";
+import {
+  showTelemetryNotice,
+  flush,
+  flushSync,
+  shouldTrack,
+  trackCommand,
+  incrementCommandCount,
+} from "./telemetry/index.js";
+
+// ---------------------------------------------------------------------------
+// CLI definition
+// ---------------------------------------------------------------------------
+
+const subCommands = {
+  init: () => import("./commands/init.js").then((m) => m.default),
+  dev: () => import("./commands/dev.js").then((m) => m.default),
+  render: () => import("./commands/render.js").then((m) => m.default),
+  lint: () => import("./commands/lint.js").then((m) => m.default),
+  info: () => import("./commands/info.js").then((m) => m.default),
+  compositions: () => import("./commands/compositions.js").then((m) => m.default),
+  benchmark: () => import("./commands/benchmark.js").then((m) => m.default),
+  browser: () => import("./commands/browser.js").then((m) => m.default),
+  docs: () => import("./commands/docs.js").then((m) => m.default),
+  doctor: () => import("./commands/doctor.js").then((m) => m.default),
+  upgrade: () => import("./commands/upgrade.js").then((m) => m.default),
+  telemetry: () => import("./commands/telemetry.js").then((m) => m.default),
+};
 
 const main = defineCommand({
   meta: {
     name: "hyperframes",
     version: VERSION,
     description: "Create and render HTML video compositions",
   },
-  subCommands: {
-    init: () => import("./commands/init.js").then((m) => m.default),
-    dev: () => import("./commands/dev.js").then((m) => m.default),
-    render: () => import("./commands/render.js").then((m) => m.default),
-    lint: () => import("./commands/lint.js").then((m) => m.default),
-    info: () => import("./commands/info.js").then((m) => m.default),
-    compositions: () => import("./commands/compositions.js").then((m) => m.default),
-    benchmark: () => import("./commands/benchmark.js").then((m) => m.default),
-    browser: () => import("./commands/browser.js").then((m) => m.default),
-    docs: () => import("./commands/docs.js").then((m) => m.default),
-    doctor: () => import("./commands/doctor.js").then((m) => m.default),
-    upgrade: () => import("./commands/upgrade.js").then((m) => m.default),
-  },
+  subCommands,
+});
+
+// ---------------------------------------------------------------------------
+// Telemetry — detect command from argv, track it, flush on exit
+// ---------------------------------------------------------------------------
+
+const commandArg = process.argv[2];
+const isHelpOrVersion =
+  process.argv.includes("--help") ||
+  process.argv.includes("--version") ||
+  process.argv.includes("-h");
+const command = commandArg && commandArg in subCommands ? commandArg : "unknown";
+
+if (command !== "telemetry" && command !== "unknown" && !isHelpOrVersion) {
+  showTelemetryNotice();
+  trackCommand(command);
+  if (shouldTrack()) {
+    incrementCommandCount();
+  }
+}
+
+// Async flush for normal exit (beforeExit fires when the event loop drains)
+process.on("beforeExit", () => {
+  flush().catch(() => {});
+});
+
+// Sync flush for process.exit() calls (exit event only allows synchronous code)
+process.on("exit", () => {
+  flushSync();
 });
 
 runMain(main);

packages/cli/src/commands/browser.ts

@@ -9,6 +9,7 @@ import {
   CHROME_VERSION,
   CACHE_DIR,
 } from "../browser/manager.js";
+import { trackBrowserInstall } from "../telemetry/events.js";
 
 async function runEnsure(): Promise<void> {
   clack.intro(c.bold("hyperframes browser ensure"));
@@ -47,6 +48,7 @@ async function runEnsure(): Promise<void> {
   });
 
   downloadSpinner.stop(c.success("Download complete"));
+  trackBrowserInstall();
 
   console.log();
   console.log(`   ${c.dim("Source:")}  ${c.bold(result.source)}`);

packages/cli/src/commands/dev.ts

@@ -5,6 +5,7 @@ import { resolve, dirname, basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as clack from "@clack/prompts";
 import { c } from "../ui/colors.js";
+import { isDevMode } from "../utils/env.js";
 
 /**
  * Check if a port is available by trying to listen on it briefly.
@@ -31,19 +32,6 @@ async function findAvailablePort(startPort: number): Promise<number> {
   return startPort; // fallback — let the server fail with a clear error
 }
 
-/**
- * Detect whether we're running from source (monorepo dev) or from the built bundle.
- * When running via tsx from source, the file is at cli/src/commands/dev.ts.
- * When running from the built bundle, the file is at cli/dist/cli.js.
- * We check the filename portion of the URL to avoid false positives from
- * directory names (e.g., /Users/someone/src/...).
- */
-function isDevMode(): boolean {
-  const url = new URL(import.meta.url);
-  // In dev mode the file is a .ts source file; in production it's a bundled .js
-  return url.pathname.endsWith(".ts");
-}
-
 export default defineCommand({
   meta: { name: "dev", description: "Start the studio for local development" },
   args: {

packages/cli/src/commands/init.ts

@@ -14,6 +14,7 @@ import { execSync, execFileSync, spawn } from "node:child_process";
 import * as clack from "@clack/prompts";
 import { c } from "../ui/colors.js";
 import { TEMPLATES, type TemplateId } from "../templates/generators.js";
+import { trackInitTemplate } from "../telemetry/events.js";
 
 const ALL_TEMPLATE_IDS = TEMPLATES.map((t) => t.id);
 
@@ -380,6 +381,7 @@ export default defineCommand({
       }
 
       scaffoldProject(destDir, basename(destDir), templateId, localVideoName);
+      trackInitTemplate(templateId);
 
       console.log(c.success(`\nCreated ${c.accent(name + "/")}`));
       for (const f of readdirSync(destDir)) {
@@ -499,6 +501,7 @@ export default defineCommand({
 
     // 4. Copy template and patch
     scaffoldProject(destDir, name, templateId, localVideoName);
+    trackInitTemplate(templateId);
 
     const files = readdirSync(destDir);
     clack.note(files.map((f) => c.accent(f)).join("\n"), c.success(`Created ${name}/`));

packages/cli/src/commands/render.ts

@@ -6,6 +6,7 @@ import { loadProducer } from "../utils/producer.js";
 import { c } from "../ui/colors.js";
 import { formatBytes, formatDuration, errorBox } from "../ui/format.js";
 import { renderProgress } from "../ui/progress.js";
+import { trackRenderComplete, trackRenderError } from "../telemetry/events.js";
 
 const VALID_FPS = new Set([24, 30, 60]);
 const VALID_QUALITY = new Set(["draft", "standard", "high"]);
@@ -158,12 +159,21 @@ async function renderDocker(
     });
     await producer.executeRenderJob(job, projectDir, outputPath);
   } catch (error: unknown) {
+    trackRenderError({ fps: options.fps, quality: options.quality, docker: true });
     const message = error instanceof Error ? error.message : String(error);
     errorBox("Render failed", message, "Try --docker for containerized rendering");
     process.exit(1);
   }
 
   const elapsed = Date.now() - startTime;
+  trackRenderComplete({
+    durationMs: elapsed,
+    fps: options.fps,
+    quality: options.quality,
+    workers: options.workers ?? 4,
+    docker: true,
+    gpu: options.gpu,
+  });
   printRenderComplete(outputPath, elapsed, options.quiet);
 }
 
@@ -191,12 +201,21 @@ async function renderLocal(
   try {
     await producer.executeRenderJob(job, projectDir, outputPath, onProgress);
   } catch (error: unknown) {
+    trackRenderError({ fps: options.fps, quality: options.quality, docker: false });
     const message = error instanceof Error ? error.message : String(error);
     errorBox("Render failed", message, "Try --docker for containerized rendering");
     process.exit(1);
   }
 
   const elapsed = Date.now() - startTime;
+  trackRenderComplete({
+    durationMs: elapsed,
+    fps: options.fps,
+    quality: options.quality,
+    workers: options.workers ?? 4,
+    docker: false,
+    gpu: options.gpu,
+  });
   printRenderComplete(outputPath, elapsed, options.quiet);
 }
 

packages/cli/src/commands/telemetry.ts

@@ -0,0 +1,85 @@
+import { defineCommand } from "citty";
+import { c } from "../ui/colors.js";
+import { readConfig, writeConfig, CONFIG_PATH } from "../telemetry/config.js";
+
+function runEnable(): void {
+  const config = readConfig();
+  config.telemetryEnabled = true;
+  writeConfig(config);
+  console.log(`\n  ${c.success("\u2713")}  Telemetry ${c.success("enabled")}\n`);
+}
+
+function runDisable(): void {
+  const config = readConfig();
+  config.telemetryEnabled = false;
+  writeConfig(config);
+  console.log(`\n  ${c.success("\u2713")}  Telemetry ${c.bold("disabled")}\n`);
+}
+
+function runStatus(): void {
+  const config = readConfig();
+  const status = config.telemetryEnabled ? c.success("enabled") : c.dim("disabled");
+  console.log();
+  console.log(`  ${c.dim("Status:")}     ${status}`);
+  console.log(`  ${c.dim("Config:")}     ${c.accent(CONFIG_PATH)}`);
+  console.log(`  ${c.dim("Commands:")}   ${c.bold(String(config.commandCount))}`);
+  console.log();
+  console.log(`  ${c.dim("Disable:")}    ${c.accent("hyperframes telemetry disable")}`);
+  console.log(`  ${c.dim("Env var:")}    ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")}`);
+  console.log();
+}
+
+export default defineCommand({
+  meta: { name: "telemetry", description: "Manage anonymous usage telemetry" },
+  args: {
+    subcommand: {
+      type: "positional",
+      description: "Subcommand: enable, disable, status",
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const subcommand = args.subcommand;
+
+    if (!subcommand || subcommand === "") {
+      console.log(`
+${c.bold("hyperframes telemetry")} ${c.dim("<subcommand>")}
+
+Manage anonymous usage data collection.
+
+${c.bold("SUBCOMMANDS:")}
+  ${c.accent("status")}    ${c.dim("Show current telemetry status")}
+  ${c.accent("enable")}    ${c.dim("Enable anonymous telemetry")}
+  ${c.accent("disable")}   ${c.dim("Disable anonymous telemetry")}
+
+${c.bold("WHAT WE COLLECT:")}
+  ${c.dim("\u2022")} Command names (init, render, dev, etc.)
+  ${c.dim("\u2022")} Render performance (duration, fps, quality)
+  ${c.dim("\u2022")} Template choices
+  ${c.dim("\u2022")} OS, architecture, Node.js version, CLI version
+
+${c.bold("WHAT WE DON'T COLLECT:")}
+  ${c.dim("\u2022")} File paths, project names, or video content
+  ${c.dim("\u2022")} IP addresses (discarded by our analytics provider)
+  ${c.dim("\u2022")} Any personally identifiable information
+
+${c.dim("You can also set")} ${c.accent("HYPERFRAMES_NO_TELEMETRY=1")} ${c.dim("to disable.")}
+`);
+      return;
+    }
+
+    switch (subcommand) {
+      case "enable":
+        return runEnable();
+      case "disable":
+        return runDisable();
+      case "status":
+        return runStatus();
+      default:
+        console.error(
+          `${c.error("Unknown subcommand:")} ${subcommand}\n\nRun ${c.accent("hyperframes telemetry --help")} for usage.`,
+        );
+        process.exit(1);
+    }
+  },
+});