@nuvio/cli 0.5.3 → 0.5.5

package/README.md

@@ -1,10 +1,22 @@
 # @nuvio/cli
 
-One-command onboarding for Nuvio in Vite + React + Tailwind projects.
+One-command onboarding for nuvio in Vite + React + Tailwind projects.
 
 ```bash
 pnpm dlx @nuvio/cli init
 pnpm dev
 ```
 
-See [Nuvio docs](https://github.com/ehah/Nuvio/blob/main/docs/nuvioUser.md).
+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

@@ -13,14 +13,19 @@ import { join } from "path";
 // src/messages.ts
 var MSG = {
   noPackageJson: "Run this from your app folder (the one with package.json).",
-  noVite: "Nuvio works with React + Vite projects. I couldn't find a Vite config here.",
-  noReact: "Nuvio needs React. Add react to this project first.",
-  noViteDep: "Nuvio needs Vite. Add vite to this project first.",
-  strictTailwind: "Nuvio expects Tailwind CSS for class edits. Install tailwindcss or pass --skip-tailwind-check.",
-  monorepoRoot: "This looks like the Nuvio monorepo. Run init in your app folder, not the tooling repo.",
+  noVite: "nuvio works with React + Vite projects. I couldn't find a Vite config here.",
+  noReact: "nuvio needs React. Add react to this project first.",
+  noViteDep: "nuvio needs Vite. Add vite to this project first.",
+  strictTailwind: "nuvio expects Tailwind CSS for class edits. Install tailwindcss or pass --skip-tailwind-check.",
+  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).'
+  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).',
+  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,216 @@ 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 SHUTDOWN_TIMEOUT_MS = 3e3;
+var client = null;
+var sessionAnonymousId = null;
+var shutdownDone = false;
+var signalHandlersRegistered = false;
+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 resolveCliInvokedCommand(help, command) {
+  if (help) return "help";
+  if (!command) return "none";
+  if (command === "init") return "init";
+  return "unknown";
+}
+function buildCliInvokedProps(command, pmOverride) {
+  const props = {
+    nuvio_version: NUVIO_VERSION,
+    os: process.platform,
+    arch: os.arch(),
+    node: process.version,
+    command
+  };
+  if (pmOverride) props.package_manager = pmOverride;
+  return props;
+}
+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 captureCliInvoked(command, pmOverride) {
+  captureCliEvent("nuvio_cli_invoked", buildCliInvokedProps(command, pmOverride));
+}
+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 flushAndShutdownClient() {
+  if (!client) return;
+  const active = client;
+  client = null;
+  await Promise.race([
+    (async () => {
+      await active.flush();
+      await active.shutdown();
+    })(),
+    new Promise((_, reject) => {
+      setTimeout(
+        () => reject(new Error("telemetry shutdown timed out")),
+        SHUTDOWN_TIMEOUT_MS
+      );
+    })
+  ]);
+}
+async function shutdownTelemetry() {
+  if (shutdownDone) return;
+  shutdownDone = true;
+  try {
+    await flushAndShutdownClient();
+    telemetryDebug("flush + shutdown complete");
+  } catch (error) {
+    telemetryDebug("shutdown failed", error);
+  }
+}
+function registerTelemetrySignalHandlers() {
+  if (signalHandlersRegistered) return;
+  signalHandlersRegistered = true;
+  const onSignal = (signal) => {
+    void (async () => {
+      await shutdownTelemetry();
+      const code2 = signal === "SIGINT" ? 130 : 143;
+      process.exit(code2);
+    })();
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+}
+
 // src/init.ts
 function isAutoYes(opts) {
   if (opts.yes) return true;
@@ -725,14 +940,14 @@ function computeTier(installOk, viteOk, appOk, starterOk) {
 function printSuccess(plan, checks) {
   if (checks.install) {
     console.log(
-      `\u2705 Nuvio packages targeted (@nuvio/vite-plugin@${NUVIO_VERSION}, @nuvio/overlay@${NUVIO_VERSION})`
+      `\u2705 nuvio packages targeted (@nuvio/vite-plugin@${NUVIO_VERSION}, @nuvio/overlay@${NUVIO_VERSION})`
     );
   }
   if (checks.vite) console.log("\u2705 Vite plugin added");
   else if (plan.failedSteps.some((s) => s.includes("vite"))) {
     console.log("\u26A0 Vite plugin \u2014 see nuvio/SETUP_TODO.md");
   }
-  if (checks.app) console.log("\u2705 Nuvio editor mounted");
+  if (checks.app) console.log("\u2705 nuvio editor mounted");
   else console.log("\u26A0 App shell \u2014 see nuvio/SETUP_TODO.md");
   if (checks.starter) {
     console.log(
@@ -753,31 +968,56 @@ Next:
 ${MSG.partialHelp}`);
   } else if (plan.tier === "partial") {
     console.log(
-      "\nNuvio helped you as far as it safely could. See warnings above."
+      "\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 +1048,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,10 +1061,14 @@ 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 {
-      console.log("\u2705 Nuvio packages already installed");
+      console.log("\u2705 nuvio packages already installed");
     }
   } else {
     console.log("(skipped install \u2014 --no-install)");
@@ -889,13 +1137,24 @@ 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;
 }
 
 // src/cli.ts
 function printHelp() {
-  console.log(`nuvio \u2014 Nuvio CLI
+  console.log(`nuvio \u2014 CLI for React + Vite
 
 Usage:
   nuvio init [options]
@@ -951,26 +1210,35 @@ function parseArgs(argv) {
   return { command, opts, help };
 }
 async function runCli(argv) {
+  registerTelemetrySignalHandlers();
   const { command, opts, help } = parseArgs(argv);
-  if (help) {
-    printHelp();
-    return 0;
-  }
-  if (!command) {
-    printHelp();
-    return 1;
-  }
-  if (command !== "init") {
-    console.error(`Unknown command: ${command}`);
-    printHelp();
-    return 1;
-  }
+  captureCliInvoked(resolveCliInvokedCommand(help, command), opts.pm);
   try {
+    if (help) {
+      printHelp();
+      return 0;
+    }
+    if (!command) {
+      printHelp();
+      return 1;
+    }
+    if (command !== "init") {
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      return 1;
+    }
     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.5",
   "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",

package/templates/AGENT.md.tpl

@@ -1,9 +1,9 @@
 <!-- nuvio-cli-template: 1 -->
-# Nuvio agent instructions
+# nuvio agent instructions
 
-This project uses [Nuvio](https://www.npmjs.com/org/nuvio) (dev-only visual editor).
+This project uses [nuvio](https://www.npmjs.com/org/nuvio) (dev-only visual editor).
 
-When the user asks to make UI editable or wire Nuvio:
+When the user asks to make UI editable or wire nuvio:
 
 1. Do **not** change unrelated files.
 2. Add **string literal** `data-nuvio-id="region.name"` on JSX elements they should click in the browser.

package/templates/README.pointer.md.tpl

@@ -1,5 +1,5 @@
 <!-- nuvio-cli-template: 1 -->
-# Nuvio
+# nuvio
 
 **Start here:** [START_HERE.md](./START_HERE.md)
 

package/templates/SETUP_TODO.md.tpl

@@ -1,5 +1,5 @@
 <!-- nuvio-cli-template: 1 -->
-# Nuvio setup — manual steps
+# nuvio setup — manual steps
 
 @nuvio/cli could not safely patch: {{FAILED_STEPS}}
 

package/templates/START_HERE.md.tpl

@@ -1,5 +1,5 @@
 <!-- nuvio-cli-template: 1 -->
-# Start here — Nuvio in this project
+# Start here — nuvio in this project
 
 Installed with @nuvio/cli@{{NUVIO_VERSION}}.
 
@@ -7,7 +7,7 @@ Installed with @nuvio/cli@{{NUVIO_VERSION}}.
 
 **Then:**
 1. Open the localhost URL from the terminal
-2. Turn **Edit** on (Nuvio chip)
+2. Turn **Edit** on (nuvio chip)
 3. Click the starter element (usually the page title — id `page.title`)
 4. **Preview Changes** → **Apply to Code**