@nuvio/cli 0.5.3 → 0.5.4

package/README.md

@@ -8,3 +8,15 @@ pnpm dev
 ```
 
 See [Nuvio docs](https://github.com/ehah/Nuvio/blob/main/docs/nuvioUser.md).
+
+## Telemetry
+
+Nuvio collects anonymous usage metrics to improve onboarding and reliability. No source code, file contents, file paths, project names, emails, or personal data are sent.
+
+Disable anytime with:
+
+```bash
+NUVIO_TELEMETRY=0
+```
+
+See [PostHog_telemetry.md](https://github.com/ehah/Nuvio/blob/main/docs/PostHog_telemetry.md).

package/dist/cli-entry.js

@@ -20,7 +20,12 @@ var MSG = {
   monorepoRoot: "This looks like the Nuvio monorepo. Run init in your app folder, not the tooling repo.",
   cliPackage: "Cannot init inside @nuvio/cli package.",
   partialHelp: "Nuvio set up what it could safely. Finish the steps in nuvio/SETUP_TODO.md, then run your dev server.",
-  noHeading: 'Nuvio is wired, but I could not find a heading to mark editable. Add data-nuvio-id="page.title" to one visible element (see nuvio/START_HERE.md).'
+  noHeading: 'Nuvio is wired, but I could not find a heading to mark editable. Add data-nuvio-id="page.title" to one visible element (see nuvio/START_HERE.md).',
+  telemetryNotice: `Nuvio collects anonymous usage metrics to improve onboarding and reliability.
+No source code, file contents, file paths, project names, emails, or personal data are sent.
+
+Disable anytime with:
+NUVIO_TELEMETRY=0`
 };
 
 // src/detect-project.ts
@@ -692,6 +697,165 @@ function printVerification(v) {
   console.log(`  Starter id page.title \u2014 ${v.starterId}`);
 }
 
+// src/telemetry.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
+import { homedir } from "os";
+import { join as join7 } from "path";
+import { randomUUID } from "crypto";
+import os from "os";
+import { PostHog } from "posthog-node";
+
+// src/nuvio-posthog-token.ts
+var NUVIO_POSTHOG_TOKEN = "phc_CJnWrLU4hB4aA88DJrPnma2WBMQqVHxUMVvrsye3R6x2";
+
+// src/telemetry.ts
+var POSTHOG_HOST = "https://us.i.posthog.com";
+function telemetryFilePath() {
+  return join7(homedir(), ".nuvio", "telemetry.json");
+}
+var FORBIDDEN_PROP_KEYS = /* @__PURE__ */ new Set([
+  "cwd",
+  "root",
+  "file",
+  "path",
+  "name",
+  "message",
+  "stack"
+]);
+var client = null;
+var sessionAnonymousId = null;
+function telemetryDebug(message, detail) {
+  if (process.env.NUVIO_TELEMETRY_DEBUG !== "1") return;
+  if (detail !== void 0) {
+    console.error(`[nuvio telemetry] ${message}`, detail);
+    return;
+  }
+  console.error(`[nuvio telemetry] ${message}`);
+}
+function isTelemetryEnabled() {
+  const flag = process.env.NUVIO_TELEMETRY;
+  if (flag === "0") return false;
+  if (flag?.toLowerCase() === "false") return false;
+  return true;
+}
+function posthogToken() {
+  return process.env.NUVIO_POSTHOG_TOKEN ?? NUVIO_POSTHOG_TOKEN;
+}
+function tokenIsConfigured(token) {
+  return Boolean(token && token.startsWith("phc_"));
+}
+function readOrCreateAnonymousId() {
+  if (sessionAnonymousId) return sessionAnonymousId;
+  try {
+    const raw = readFileSync10(telemetryFilePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.anonymousId) {
+      sessionAnonymousId = parsed.anonymousId;
+      return parsed.anonymousId;
+    }
+  } catch {
+  }
+  const id = randomUUID();
+  sessionAnonymousId = id;
+  try {
+    mkdirSync2(join7(homedir(), ".nuvio"), { recursive: true, mode: 448 });
+    writeFileSync6(
+      telemetryFilePath(),
+      JSON.stringify({ anonymousId: id }, null, 2),
+      { mode: 384 }
+    );
+  } catch {
+  }
+  return id;
+}
+function getClient() {
+  if (!isTelemetryEnabled()) return null;
+  const token = posthogToken();
+  if (!tokenIsConfigured(token)) return null;
+  if (!client) {
+    client = new PostHog(token, {
+      host: POSTHOG_HOST,
+      flushAt: 1,
+      flushInterval: 0
+    });
+    telemetryDebug("PostHog client initialized", {
+      host: POSTHOG_HOST,
+      tokenPrefix: `${token.slice(0, 8)}\u2026`
+    });
+  }
+  return client;
+}
+function sanitizeProps(props) {
+  if (!props) return void 0;
+  const out = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (FORBIDDEN_PROP_KEYS.has(key)) continue;
+    if (value === void 0) continue;
+    if (typeof value === "string" && /[/\\]/.test(value)) continue;
+    out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function buildCliTelemetryProps(pm, project) {
+  const props = {
+    nuvio_version: NUVIO_VERSION,
+    os: process.platform,
+    arch: os.arch(),
+    node: process.version
+  };
+  if (pm) props.package_manager = pm;
+  if (project) {
+    props.has_react = true;
+    props.has_vite = true;
+    props.has_tailwind = project.tailwindOk;
+  }
+  return props;
+}
+function preflightErrorCode(message) {
+  if (message === MSG.noPackageJson) return "preflight_no_package_json";
+  if (message === MSG.noVite) return "preflight_no_vite";
+  if (message === MSG.noReact) return "preflight_no_react";
+  if (message === MSG.noViteDep) return "preflight_no_vite_dep";
+  if (message === MSG.monorepoRoot || message === MSG.cliPackage) {
+    return "preflight_monorepo";
+  }
+  return "preflight_unknown";
+}
+function captureCliEvent(event, props) {
+  try {
+    if (!isTelemetryEnabled()) {
+      telemetryDebug(`skipped ${event} (telemetry disabled)`);
+      return;
+    }
+    const ph = getClient();
+    if (!ph) {
+      telemetryDebug(`skipped ${event} (no PostHog client \u2014 check token)`);
+      return;
+    }
+    const distinctId = readOrCreateAnonymousId();
+    ph.capture({
+      distinctId,
+      event,
+      properties: sanitizeProps(props)
+    });
+    telemetryDebug(`captured ${event}`, { distinctId });
+  } catch (error) {
+    telemetryDebug(`capture failed for ${event}`, error);
+  }
+}
+async function shutdownTelemetry() {
+  try {
+    if (client) {
+      await client.flush();
+      await client.shutdown();
+      client = null;
+      telemetryDebug("flush + shutdown complete");
+    }
+  } catch (error) {
+    telemetryDebug("shutdown failed", error);
+  }
+}
+
 // src/init.ts
 function isAutoYes(opts) {
   if (opts.yes) return true;
@@ -756,28 +920,53 @@ ${MSG.partialHelp}`);
       "\nNuvio helped you as far as it safely could. See warnings above."
     );
   }
+  console.log(`
+${MSG.telemetryNotice}`);
 }
 async function runInit(opts) {
   const root = opts.cwd;
+  const pm = detectPackageManager(root, opts.pm);
+  if (!opts.dryRun) {
+    captureCliEvent(
+      "nuvio_init_started",
+      buildCliTelemetryProps(pm)
+    );
+  }
   let project;
   try {
     project = detectProject(root);
   } catch (e) {
     if (e instanceof PreflightError) {
       console.error(e.message);
+      if (!opts.dryRun) {
+        captureCliEvent("nuvio_init_failed", {
+          ...buildCliTelemetryProps(pm),
+          error_code: preflightErrorCode(e.message)
+        });
+      }
       return 1;
     }
     if (opts.verbose) console.error(e);
     console.error("Something went wrong. Run with --verbose for details.");
+    if (!opts.dryRun) {
+      captureCliEvent("nuvio_init_failed", {
+        ...buildCliTelemetryProps(pm),
+        error_code: "unexpected_error"
+      });
+    }
     return 2;
   }
-  const pm = detectPackageManager(root, opts.pm);
+  const projectProps = buildCliTelemetryProps(pm, project);
   const plan = createPlan(root, pm);
   plan.installCommand = opts.noInstall ? "(skipped \u2014 --no-install)" : installCommand(pm, NUVIO_VERSION);
   if (project.tailwindWarn && !opts.skipTailwindCheck) {
     const msg = "Tailwind CSS not detected. Class/style edits may not work until Tailwind is installed.";
     if (opts.strict) {
       console.error(MSG.strictTailwind);
+      captureCliEvent("nuvio_init_failed", {
+        ...projectProps,
+        error_code: "strict_tailwind"
+      });
       return 1;
     }
     plan.warnings.push(msg);
@@ -808,6 +997,10 @@ async function runInit(opts) {
     const ok = await confirm(plan);
     if (!ok) {
       console.log("Cancelled.");
+      captureCliEvent("nuvio_init_failed", {
+        ...projectProps,
+        error_code: "user_cancelled"
+      });
       return 1;
     }
   }
@@ -817,6 +1010,10 @@ async function runInit(opts) {
       const result = runInstall(root, pm, NUVIO_VERSION);
       if (!result.ok) {
         console.error(result.message ?? "Install failed.");
+        captureCliEvent("nuvio_init_failed", {
+          ...projectProps,
+          error_code: "install_failed"
+        });
         return 1;
       }
     } else {
@@ -889,7 +1086,18 @@ async function runInit(opts) {
     project.viteConfigPath
   );
   printVerification(verification);
-  if (plan.tier === "failed") return 1;
+  if (plan.tier === "failed") {
+    captureCliEvent("nuvio_init_failed", {
+      ...projectProps,
+      error_code: "init_tier_failed",
+      result_tier: "failed"
+    });
+    return 1;
+  }
+  captureCliEvent("nuvio_init_completed", {
+    ...projectProps,
+    result_tier: plan.tier
+  });
   return plan.tier === "partial" || plan.tier === "full" ? 0 : 1;
 }
 
@@ -968,9 +1176,16 @@ async function runCli(argv) {
   try {
     return await runInit(opts);
   } catch (e) {
+    const pm = detectPackageManager(opts.cwd, opts.pm);
+    captureCliEvent("nuvio_init_failed", {
+      ...buildCliTelemetryProps(pm),
+      error_code: "unexpected_error"
+    });
     if (opts.verbose) console.error(e);
     else console.error("Something went wrong. Run with --verbose for details.");
     return 2;
+  } finally {
+    await shutdownTelemetry();
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuvio/cli",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Nuvio CLI: one-command Vite + React onboarding (nuvio init).",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,8 @@
     "@babel/parser": "^7.26.9",
     "@babel/traverse": "^7.26.9",
     "@babel/types": "^7.26.9",
-    "fast-glob": "^3.3.3"
+    "fast-glob": "^3.3.3",
+    "posthog-node": "^5.36.2"
   },
   "devDependencies": {
     "@types/babel__generator": "^7.6.8",