@nuvio/cli 0.5.4 → 1.0.0

package/dist/cli-entry.js

@@ -3,25 +3,48 @@
 // src/cli.ts
 import { resolve } from "path";
 
-// src/init.ts
-import { createInterface } from "readline";
+// src/detect-pm.ts
+import { existsSync } from "fs";
+import { join } from "path";
+function detectPackageManager(root, override) {
+  if (override) return override;
+  if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(root, "package-lock.json"))) return "npm";
+  if (existsSync(join(root, "yarn.lock"))) return "yarn";
+  if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+    return "bun";
+  return "npm";
+}
+function installCommand(pm, version) {
+  const pkgs = `@nuvio/vite-plugin@${version} @nuvio/overlay@${version}`;
+  switch (pm) {
+    case "pnpm":
+      return `pnpm add -D ${pkgs}`;
+    case "yarn":
+      return `yarn add -D ${pkgs}`;
+    case "bun":
+      return `bun add -d ${pkgs}`;
+    default:
+      return `npm install -D ${pkgs}`;
+  }
+}
 
 // src/detect-project.ts
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { join as join2 } 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).',
-  telemetryNotice: `Nuvio collects anonymous usage metrics to improve onboarding and reliability.
+  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:
@@ -50,8 +73,8 @@ function detectTailwind(root, pkg) {
   if (hasDep(pkg, "tailwindcss")) return true;
   const cssCandidates = ["src/index.css", "src/App.css"];
   for (const rel of cssCandidates) {
-    const p = join(root, rel);
-    if (!existsSync(p)) continue;
+    const p = join2(root, rel);
+    if (!existsSync2(p)) continue;
     const text = readFileSync(p, "utf8");
     if (text.includes("@tailwind") || text.includes('@import "tailwindcss"') || text.includes("@import 'tailwindcss'")) {
       return true;
@@ -60,8 +83,8 @@ function detectTailwind(root, pkg) {
   return false;
 }
 function detectProject(root) {
-  const packageJsonPath = join(root, "package.json");
-  if (!existsSync(packageJsonPath)) {
+  const packageJsonPath = join2(root, "package.json");
+  if (!existsSync2(packageJsonPath)) {
     throw new PreflightError(MSG.noPackageJson);
   }
   const packageJson = JSON.parse(
@@ -76,8 +99,8 @@ function detectProject(root) {
   let viteConfigPath = "";
   let viteConfigName = "";
   for (const name of VITE_CONFIGS) {
-    const p = join(root, name);
-    if (existsSync(p)) {
+    const p = join2(root, name);
+    if (existsSync2(p)) {
       viteConfigPath = p;
       viteConfigName = name;
       break;
@@ -104,243 +127,314 @@ function detectProject(root) {
   };
 }
 
-// src/detect-pm.ts
-import { existsSync as existsSync2 } from "fs";
-import { join as join2 } from "path";
-function detectPackageManager(root, override) {
-  if (override) return override;
-  if (existsSync2(join2(root, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync2(join2(root, "package-lock.json"))) return "npm";
-  if (existsSync2(join2(root, "yarn.lock"))) return "yarn";
-  if (existsSync2(join2(root, "bun.lockb")) || existsSync2(join2(root, "bun.lock")))
-    return "bun";
-  return "npm";
+// src/nuvio-deps.ts
+import { readFileSync as readFileSync2 } from "fs";
+function readPackageJson(packageJsonPath) {
+  return JSON.parse(readFileSync2(packageJsonPath, "utf8"));
 }
-function installCommand(pm, version) {
-  const pkgs = `@nuvio/vite-plugin@${version} @nuvio/overlay@${version}`;
-  switch (pm) {
-    case "pnpm":
-      return `pnpm add -D ${pkgs}`;
-    case "yarn":
-      return `yarn add -D ${pkgs}`;
-    case "bun":
-      return `bun add -d ${pkgs}`;
-    default:
-      return `npm install -D ${pkgs}`;
-  }
+function getDependencyVersion(pkg, name) {
+  const deps = pkg.dependencies;
+  const devDeps = pkg.devDependencies;
+  return deps?.[name] ?? devDeps?.[name];
+}
+function hasNuvioDependency(pkg, name) {
+  return Boolean(getDependencyVersion(pkg, name));
+}
+function hasNuvioPackages(pkg) {
+  return hasNuvioDependency(pkg, "@nuvio/vite-plugin") && hasNuvioDependency(pkg, "@nuvio/overlay");
+}
+function isWorkspaceLinkedVersion(version) {
+  if (!version) return false;
+  return version.startsWith("workspace:") || version.startsWith("link:") || version.startsWith("file:");
+}
+function nuvioOverlayLinkKind(pkg) {
+  const raw = getDependencyVersion(pkg, "@nuvio/overlay");
+  if (!raw) return "missing";
+  return isWorkspaceLinkedVersion(raw) ? "workspace" : "npm";
 }
 
-// src/install-packages.ts
-import { spawnSync } from "child_process";
-import { readFileSync as readFileSync2 } from "fs";
-function parseInstalledVersion(pkg, name) {
-  const dev = pkg.devDependencies;
-  const deps = pkg.dependencies;
-  const raw = dev?.[name] ?? deps?.[name];
-  if (!raw) return null;
-  return raw.replace(/^[\^~]/, "");
+// src/project-scan.ts
+import { relative } from "path";
+import {
+  buildSourceIndex,
+  detectProjectLibraries,
+  NUVIO_DEFAULT_SCAN_GLOBS
+} from "@nuvio/vite-plugin/scan";
+var SCAN_GLOBS = [...NUVIO_DEFAULT_SCAN_GLOBS, "app/**/*.{tsx,jsx}"];
+function scanProject(root) {
+  const ctx = detectProject(root);
+  const detectedLibraries = detectProjectLibraries(root, ctx.packageJson);
+  const index = buildSourceIndex(root, SCAN_GLOBS, { detectedLibraries });
+  return { ctx, detectedLibraries, index };
 }
-function packagesNeedInstall(packageJsonPath, targetVersion) {
-  const pkg = JSON.parse(readFileSync2(packageJsonPath, "utf8"));
-  for (const name of ["@nuvio/vite-plugin", "@nuvio/overlay"]) {
-    const v = parseInstalledVersion(pkg, name);
-    if (v !== targetVersion) return true;
-  }
-  return false;
+function relPath(root, fileAbs) {
+  return relative(root, fileAbs).replace(/\\/g, "/");
 }
-function runInstall(root, pm, version) {
-  const cmd = installCommand(pm, version);
-  const result = spawnSync(cmd, {
-    cwd: root,
-    shell: true,
-    stdio: "inherit",
-    env: process.env
-  });
-  if (result.status !== 0) {
-    return {
-      ok: false,
-      message: `Install failed. Try manually:
-  ${cmd}`
-    };
+function isTableHost(entry) {
+  return entry.hierarchyRole === "table" || entry.id.endsWith(".table") || entry.id.includes(".header.") || /\.row\./.test(entry.id);
+}
+function aggregateClassNameModes(entries) {
+  const counts = {};
+  for (const entry of entries) {
+    const mode = entry.classNameMode ?? "literal-only";
+    counts[mode] = (counts[mode] ?? 0) + 1;
   }
-  return { ok: true };
+  return counts;
 }
 
-// src/babel-traverse.ts
-import traverseImport from "@babel/traverse";
-var traverse = typeof traverseImport === "function" ? traverseImport : traverseImport.default;
-var babel_traverse_default = traverse;
-
-// src/patch-vite-config.ts
-import * as t from "@babel/types";
-import { readFileSync as readFileSync3, writeFileSync } from "fs";
+// src/telemetry.ts
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join as join3 } from "path";
+import { randomUUID } from "crypto";
+import os from "os";
+import { PostHog } from "posthog-node";
 
-// src/babel-generator.ts
-import generateImport from "@babel/generator";
-var generate = typeof generateImport === "function" ? generateImport : generateImport.default;
-var babel_generator_default = generate;
+// src/nuvio-posthog-token.ts
+var NUVIO_POSTHOG_TOKEN = "phc_CJnWrLU4hB4aA88DJrPnma2WBMQqVHxUMVvrsye3R6x2";
 
-// src/parse-ts.ts
-import { parse } from "@babel/parser";
-var PARSE_OPTS = {
-  sourceType: "module",
-  plugins: ["typescript", "jsx"]
-};
-function parseTs(source, filename = "file.tsx") {
-  return parse(source, {
-    ...PARSE_OPTS,
-    sourceFilename: filename
-  });
-}
-function printTs(ast, source) {
-  const out = babel_generator_default(ast, { retainLines: true }, source);
-  return out.code.endsWith("\n") ? out.code : `${out.code}
-`;
-}
+// src/version.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var NUVIO_VERSION = require2("../package.json").version;
 
-// src/patch-vite-config.ts
-function hasNuvioImport(ast) {
-  let found = false;
-  babel_traverse_default(ast, {
-    ImportDeclaration(path) {
-      if (path.node.source.value === "@nuvio/vite-plugin") found = true;
-    }
-  });
-  return found;
+// src/telemetry.ts
+var POSTHOG_HOST = "https://us.i.posthog.com";
+function telemetryFilePath() {
+  return join3(homedir(), ".nuvio", "telemetry.json");
 }
-function hasNuvioPluginCall(ast) {
-  let found = false;
-  babel_traverse_default(ast, {
-    CallExpression(path) {
-      if (t.isIdentifier(path.node.callee, { name: "nuvio" })) found = true;
-    }
-  });
-  return found;
+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}`);
 }
-var OVERLAY_DEP = "@nuvio/overlay";
-function excludeListsOverlay(expr) {
-  if (!expr || !t.isArrayExpression(expr)) return false;
-  return expr.elements.some(
-    (el) => t.isStringLiteral(el) && el.value === OVERLAY_DEP
-  );
+function isTelemetryEnabled() {
+  const flag = process.env.NUVIO_TELEMETRY;
+  if (flag === "0") return false;
+  if (flag?.toLowerCase() === "false") return false;
+  return true;
 }
-function ensureOptimizeDepsExclude(ast) {
-  let patched = false;
-  babel_traverse_default(ast, {
-    CallExpression(path) {
-      const callee = path.node.callee;
-      if (!t.isIdentifier(callee, { name: "defineConfig" })) return;
-      const arg = path.node.arguments[0];
-      if (!t.isObjectExpression(arg)) return;
-      let optimizeDeps;
-      for (const prop of arg.properties) {
-        if (t.isObjectProperty(prop) && t.isIdentifier(prop.key, { name: "optimizeDeps" })) {
-          optimizeDeps = prop;
-          break;
-        }
-      }
-      if (!optimizeDeps) {
-        arg.properties.push(
-          t.objectProperty(
-            t.identifier("optimizeDeps"),
-            t.objectExpression([
-              t.objectProperty(
-                t.identifier("exclude"),
-                t.arrayExpression([t.stringLiteral(OVERLAY_DEP)])
-              )
-            ])
-          )
-        );
-        patched = true;
-        return;
-      }
-      if (!t.isObjectExpression(optimizeDeps.value)) return;
-      let excludeProp;
-      for (const p of optimizeDeps.value.properties) {
-        if (t.isObjectProperty(p) && t.isIdentifier(p.key, { name: "exclude" })) {
-          excludeProp = p;
-          break;
-        }
-      }
-      if (!excludeProp) {
-        optimizeDeps.value.properties.push(
-          t.objectProperty(
-            t.identifier("exclude"),
-            t.arrayExpression([t.stringLiteral(OVERLAY_DEP)])
-          )
-        );
-        patched = true;
-        return;
-      }
-      if (t.isArrayExpression(excludeProp.value) && !excludeListsOverlay(excludeProp.value)) {
-        excludeProp.value.elements.push(t.stringLiteral(OVERLAY_DEP));
-        patched = true;
-      }
-    }
-  });
-  return patched;
+function posthogToken() {
+  return process.env.NUVIO_POSTHOG_TOKEN ?? NUVIO_POSTHOG_TOKEN;
 }
-function viteConfigHasOverlayOptimizeExclude(filePath) {
-  const source = readFileSync3(filePath, "utf8");
-  return /optimizeDeps\s*:\s*\{[^}]*exclude\s*:\s*\[[^\]]*@nuvio\/overlay/.test(
-    source
-  ) || /exclude\s*:\s*\[[^\]]*["']@nuvio\/overlay["']/.test(source);
+function tokenIsConfigured(token) {
+  return Boolean(token && token.startsWith("phc_"));
 }
-function appendNuvioPlugin(ast) {
-  let patched = false;
-  babel_traverse_default(ast, {
-    ObjectProperty(path) {
-      if (!t.isIdentifier(path.node.key, { name: "plugins" })) return;
-      if (!t.isArrayExpression(path.node.value)) return;
-      path.node.value.elements.push(t.callExpression(t.identifier("nuvio"), []));
-      patched = true;
+function readOrCreateAnonymousId() {
+  if (sessionAnonymousId) return sessionAnonymousId;
+  try {
+    const raw = readFileSync3(telemetryFilePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.anonymousId) {
+      sessionAnonymousId = parsed.anonymousId;
+      return parsed.anonymousId;
     }
-  });
-  return patched;
-}
-function patchViteConfigFile(filePath) {
-  const source = readFileSync3(filePath, "utf8");
-  let ast;
+  } catch {
+  }
+  const id = randomUUID();
+  sessionAnonymousId = id;
   try {
-    ast = parseTs(source, filePath);
+    mkdirSync(join3(homedir(), ".nuvio"), { recursive: true, mode: 448 });
+    writeFileSync(
+      telemetryFilePath(),
+      JSON.stringify({ anonymousId: id }, null, 2),
+      { mode: 384 }
+    );
   } catch {
-    return { ok: false, error: "parse failed" };
   }
-  const depsPatched = ensureOptimizeDepsExclude(ast);
-  const alreadyPlugin = hasNuvioImport(ast) && hasNuvioPluginCall(ast);
-  if (alreadyPlugin && !depsPatched) {
-    return { ok: true, skipped: true };
+  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`
+    });
   }
-  if (!hasNuvioImport(ast)) {
-    ast.program.body.unshift(
-      t.importDeclaration(
-        [t.importSpecifier(t.identifier("nuvio"), t.identifier("nuvio"))],
-        t.stringLiteral("@nuvio/vite-plugin")
-      )
-    );
+  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;
   }
-  if (!hasNuvioPluginCall(ast)) {
-    if (!appendNuvioPlugin(ast)) {
-      return { ok: false, error: "no static plugins array" };
+  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";
+  if (command === "doctor") return "doctor";
+  if (command === "scan") return "scan";
+  if (command === "stats") return "stats";
+  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);
   }
-  writeFileSync(filePath, printTs(ast, source), "utf8");
-  return { ok: true, skipped: alreadyPlugin && depsPatched };
 }
-function viteConfigHasNuvio(filePath) {
-  const source = readFileSync3(filePath, "utf8");
-  try {
-    const ast = parseTs(source, filePath);
-    return hasNuvioImport(ast) && hasNuvioPluginCall(ast);
-  } catch {
-    return /nuvio\s*\(/.test(source);
-  }
+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/babel-traverse.ts
+import traverseImport from "@babel/traverse";
+var traverse = typeof traverseImport === "function" ? traverseImport : traverseImport.default;
+var babel_traverse_default = traverse;
+
+// src/patch-app-root.ts
+import * as t from "@babel/types";
+import fg from "fast-glob";
+import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { join as join4 } from "path";
+
+// src/babel-generator.ts
+import generateImport from "@babel/generator";
+var generate = typeof generateImport === "function" ? generateImport : generateImport.default;
+var babel_generator_default = generate;
+
+// src/parse-ts.ts
+import { parse } from "@babel/parser";
+var PARSE_OPTS = {
+  sourceType: "module",
+  plugins: ["typescript", "jsx"]
+};
+function parseTs(source, filename = "file.tsx") {
+  return parse(source, {
+    ...PARSE_OPTS,
+    sourceFilename: filename
+  });
+}
+function printTs(ast, source) {
+  const out = babel_generator_default(ast, { retainLines: true }, source);
+  return out.code.endsWith("\n") ? out.code : `${out.code}
+`;
 }
 
 // src/patch-app-root.ts
-import * as t2 from "@babel/types";
-import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
-import { join as join3 } from "path";
 var APP_CANDIDATES = [
   "src/App.tsx",
   "src/App.jsx",
@@ -349,7 +443,7 @@ var APP_CANDIDATES = [
 ];
 function resolveAppFile(root) {
   for (const rel of APP_CANDIDATES) {
-    const p = join3(root, rel);
+    const p = join4(root, rel);
     if (existsSync3(p)) return p;
   }
   return null;
@@ -368,19 +462,19 @@ function hasDevShell(ast) {
   babel_traverse_default(ast, {
     JSXElement(path) {
       const name = path.node.openingElement.name;
-      if (t2.isJSXIdentifier(name) && name.name === "NuvioDevShell") found = true;
+      if (t.isJSXIdentifier(name) && name.name === "NuvioDevShell") found = true;
     }
   });
   return found;
 }
 function unwrapJsx(node) {
   if (!node) return null;
-  if (t2.isJSXElement(node) || t2.isJSXFragment(node)) return node;
-  if (t2.isParenthesizedExpression(node)) return unwrapJsx(node.expression);
+  if (t.isJSXElement(node) || t.isJSXFragment(node)) return node;
+  if (t.isParenthesizedExpression(node)) return unwrapJsx(node.expression);
   return null;
 }
-var devShellElement = t2.jsxElement(
-  t2.jsxOpeningElement(t2.jsxIdentifier("NuvioDevShell"), [], true),
+var devShellElement = t.jsxElement(
+  t.jsxOpeningElement(t.jsxIdentifier("NuvioDevShell"), [], true),
   null,
   [],
   true
@@ -391,15 +485,15 @@ function appendDevShell(ast) {
     ReturnStatement(path) {
       const jsx = unwrapJsx(path.node.argument);
       if (!jsx) return;
-      if (t2.isJSXFragment(jsx)) {
-        jsx.children.push(t2.jsxText("\n      "));
+      if (t.isJSXFragment(jsx)) {
+        jsx.children.push(t.jsxText("\n      "));
         jsx.children.push(devShellElement);
         patched = true;
       } else {
-        path.node.argument = t2.jsxFragment(
-          t2.jsxOpeningFragment(),
-          t2.jsxClosingFragment(),
-          [jsx, t2.jsxText("\n      "), devShellElement]
+        path.node.argument = t.jsxFragment(
+          t.jsxOpeningFragment(),
+          t.jsxClosingFragment(),
+          [jsx, t.jsxText("\n      "), devShellElement]
         );
         patched = true;
       }
@@ -420,14 +514,14 @@ function patchAppRootFile(filePath) {
   }
   if (!hasOverlayImport(ast)) {
     ast.program.body.unshift(
-      t2.importDeclaration(
+      t.importDeclaration(
         [
-          t2.importSpecifier(
-            t2.identifier("NuvioDevShell"),
-            t2.identifier("NuvioDevShell")
+          t.importSpecifier(
+            t.identifier("NuvioDevShell"),
+            t.identifier("NuvioDevShell")
           )
         ],
-        t2.stringLiteral("@nuvio/overlay")
+        t.stringLiteral("@nuvio/overlay")
       )
     );
   }
@@ -447,22 +541,32 @@ function appHasDevShell(filePath) {
     return /NuvioDevShell/.test(source);
   }
 }
+function projectHasDevShell(root) {
+  const appFile = resolveAppFile(root);
+  if (appFile && appHasDevShell(appFile)) return true;
+  const files = fg.sync(["src/**/*.{tsx,jsx}"], {
+    cwd: root,
+    absolute: true,
+    onlyFiles: true
+  });
+  for (const file of files) {
+    if (appHasDevShell(file)) return true;
+  }
+  return false;
+}
 
 // src/patch-main-styles.ts
 import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 var MAIN_CANDIDATES = ["src/main.tsx", "src/main.jsx", "main.tsx", "main.jsx"];
 var STYLE_IMPORT = 'import "@nuvio/overlay/style.css";';
 function overlayInstalledFromNpm(packageJsonPath) {
-  const pkg = JSON.parse(readFileSync5(packageJsonPath, "utf8"));
-  const dev = pkg.devDependencies;
-  const raw = dev?.["@nuvio/overlay"];
-  if (!raw) return false;
-  return !raw.startsWith("workspace:") && !raw.startsWith("link:") && !raw.startsWith("file:");
+  const pkg = readPackageJson(packageJsonPath);
+  return nuvioOverlayLinkKind(pkg) === "npm";
 }
 function resolveMainEntry(root) {
   for (const rel of MAIN_CANDIDATES) {
-    const p = join4(root, rel);
+    const p = join5(root, rel);
     if (existsSync4(p)) return p;
   }
   return null;
@@ -490,19 +594,156 @@ function patchMainOverlayStyles(mainPath) {
   return { ok: true };
 }
 
-// src/patch-starter-id.ts
-import * as t3 from "@babel/types";
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+// src/patch-vite-config.ts
+import * as t2 from "@babel/types";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+function hasNuvioImport(ast) {
+  let found = false;
+  babel_traverse_default(ast, {
+    ImportDeclaration(path) {
+      if (path.node.source.value === "@nuvio/vite-plugin") found = true;
+    }
+  });
+  return found;
+}
+function hasNuvioPluginCall(ast) {
+  let found = false;
+  babel_traverse_default(ast, {
+    CallExpression(path) {
+      if (t2.isIdentifier(path.node.callee, { name: "nuvio" })) found = true;
+    }
+  });
+  return found;
+}
+var OVERLAY_DEP = "@nuvio/overlay";
+function excludeListsOverlay(expr) {
+  if (!expr || !t2.isArrayExpression(expr)) return false;
+  return expr.elements.some(
+    (el) => t2.isStringLiteral(el) && el.value === OVERLAY_DEP
+  );
+}
+function ensureOptimizeDepsExclude(ast) {
+  let patched = false;
+  babel_traverse_default(ast, {
+    CallExpression(path) {
+      const callee = path.node.callee;
+      if (!t2.isIdentifier(callee, { name: "defineConfig" })) return;
+      const arg = path.node.arguments[0];
+      if (!t2.isObjectExpression(arg)) return;
+      let optimizeDeps;
+      for (const prop of arg.properties) {
+        if (t2.isObjectProperty(prop) && t2.isIdentifier(prop.key, { name: "optimizeDeps" })) {
+          optimizeDeps = prop;
+          break;
+        }
+      }
+      if (!optimizeDeps) {
+        arg.properties.push(
+          t2.objectProperty(
+            t2.identifier("optimizeDeps"),
+            t2.objectExpression([
+              t2.objectProperty(
+                t2.identifier("exclude"),
+                t2.arrayExpression([t2.stringLiteral(OVERLAY_DEP)])
+              )
+            ])
+          )
+        );
+        patched = true;
+        return;
+      }
+      if (!t2.isObjectExpression(optimizeDeps.value)) return;
+      let excludeProp;
+      for (const p of optimizeDeps.value.properties) {
+        if (t2.isObjectProperty(p) && t2.isIdentifier(p.key, { name: "exclude" })) {
+          excludeProp = p;
+          break;
+        }
+      }
+      if (!excludeProp) {
+        optimizeDeps.value.properties.push(
+          t2.objectProperty(
+            t2.identifier("exclude"),
+            t2.arrayExpression([t2.stringLiteral(OVERLAY_DEP)])
+          )
+        );
+        patched = true;
+        return;
+      }
+      if (t2.isArrayExpression(excludeProp.value) && !excludeListsOverlay(excludeProp.value)) {
+        excludeProp.value.elements.push(t2.stringLiteral(OVERLAY_DEP));
+        patched = true;
+      }
+    }
+  });
+  return patched;
+}
+function viteConfigHasOverlayOptimizeExclude(filePath) {
+  const source = readFileSync6(filePath, "utf8");
+  return /optimizeDeps\s*:\s*\{[^}]*exclude\s*:\s*\[[^\]]*@nuvio\/overlay/.test(
+    source
+  ) || /exclude\s*:\s*\[[^\]]*["']@nuvio\/overlay["']/.test(source);
+}
+function appendNuvioPlugin(ast) {
+  let patched = false;
+  babel_traverse_default(ast, {
+    ObjectProperty(path) {
+      if (!t2.isIdentifier(path.node.key, { name: "plugins" })) return;
+      if (!t2.isArrayExpression(path.node.value)) return;
+      path.node.value.elements.push(t2.callExpression(t2.identifier("nuvio"), []));
+      patched = true;
+    }
+  });
+  return patched;
+}
+function patchViteConfigFile(filePath) {
+  const source = readFileSync6(filePath, "utf8");
+  let ast;
+  try {
+    ast = parseTs(source, filePath);
+  } catch {
+    return { ok: false, error: "parse failed" };
+  }
+  const depsPatched = ensureOptimizeDepsExclude(ast);
+  const alreadyPlugin = hasNuvioImport(ast) && hasNuvioPluginCall(ast);
+  if (alreadyPlugin && !depsPatched) {
+    return { ok: true, skipped: true };
+  }
+  if (!hasNuvioImport(ast)) {
+    ast.program.body.unshift(
+      t2.importDeclaration(
+        [t2.importSpecifier(t2.identifier("nuvio"), t2.identifier("nuvio"))],
+        t2.stringLiteral("@nuvio/vite-plugin")
+      )
+    );
+  }
+  if (!hasNuvioPluginCall(ast)) {
+    if (!appendNuvioPlugin(ast)) {
+      return { ok: false, error: "no static plugins array" };
+    }
+  }
+  writeFileSync4(filePath, printTs(ast, source), "utf8");
+  return { ok: true, skipped: alreadyPlugin && depsPatched };
+}
+function viteConfigHasNuvio(filePath) {
+  const source = readFileSync6(filePath, "utf8");
+  try {
+    const ast = parseTs(source, filePath);
+    return hasNuvioImport(ast) && hasNuvioPluginCall(ast);
+  } catch {
+    return /nuvio\s*\(/.test(source);
+  }
+}
 
 // src/scan-ids.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { join as join5 } from "path";
-import fg from "fast-glob";
+import { readFileSync as readFileSync7 } from "fs";
+import { join as join6 } from "path";
+import fg2 from "fast-glob";
 var ID_GLOB = ["src/**/*.{tsx,jsx}"];
 function projectHasPageTitleId(root) {
-  const files = fg.sync(ID_GLOB, { cwd: root, absolute: true });
+  const files = fg2.sync(ID_GLOB, { cwd: root, absolute: true });
   for (const file of files) {
-    const text = readFileSync6(file, "utf8");
+    const text = readFileSync7(file, "utf8");
     if (/data-nuvio-id=["']page\.title["']/.test(text)) {
       return true;
     }
@@ -510,10 +751,10 @@ function projectHasPageTitleId(root) {
   return false;
 }
 function findHeadingFiles(root) {
-  const files = fg.sync(ID_GLOB, { cwd: root, absolute: true });
+  const files = fg2.sync(ID_GLOB, { cwd: root, absolute: true });
   const ordered = [
-    join5(root, "src/App.tsx"),
-    join5(root, "src/App.jsx"),
+    join6(root, "src/App.tsx"),
+    join6(root, "src/App.jsx"),
     ...files.filter(
       (f) => !f.endsWith("App.tsx") && !f.endsWith("App.jsx")
     )
@@ -532,9 +773,239 @@ function findHeadingFiles(root) {
   return out;
 }
 
+// src/verify.ts
+function optimizeDepsSatisfied(viteConfigPath, packageJsonPath) {
+  if (viteConfigHasOverlayOptimizeExclude(viteConfigPath)) return true;
+  const pkg = readPackageJson(packageJsonPath);
+  return nuvioOverlayLinkKind(pkg) === "workspace";
+}
+function verifyProject(root, packageJsonPath, viteConfigPath) {
+  const pkg = readPackageJson(packageJsonPath);
+  const depsOk = hasNuvioPackages(pkg);
+  const mainEntry = resolveMainEntry(root);
+  return {
+    deps: depsOk ? "OK" : "MISSING",
+    vite: viteConfigHasNuvio(viteConfigPath) ? "OK" : "TODO",
+    overlayCss: mainEntry && (mainHasOverlayStyles(mainEntry) || !overlayInstalledFromNpm(packageJsonPath)) ? "OK" : "TODO",
+    optimizeDeps: optimizeDepsSatisfied(viteConfigPath, packageJsonPath) ? "OK" : "TODO",
+    shell: projectHasDevShell(root) ? "OK" : "TODO",
+    starterId: projectHasPageTitleId(root) ? "OK" : "MISSING"
+  };
+}
+function printVerification(v) {
+  console.log("Verification:");
+  console.log(
+    `  dependencies: @nuvio/vite-plugin, @nuvio/overlay \u2014 ${v.deps}`
+  );
+  console.log(`  vite.config: nuvio() \u2014 ${v.vite}`);
+  console.log(`  main.tsx: @nuvio/overlay/style.css \u2014 ${v.overlayCss}`);
+  console.log(`  vite.config: optimizeDeps exclude overlay \u2014 ${v.optimizeDeps}`);
+  console.log(`  App shell: NuvioDevShell \u2014 ${v.shell}`);
+  console.log(`  Starter id page.title \u2014 ${v.starterId}`);
+}
+
+// src/doctor.ts
+async function checkDevServerReachable(port) {
+  const url = `http://127.0.0.1:${port}/`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
+    if (res.ok) {
+      return {
+        id: "dev_server",
+        label: `Dev server reachable (${url})`,
+        status: "pass"
+      };
+    }
+    return {
+      id: "dev_server",
+      label: "Dev server reachable",
+      status: "warn",
+      detail: `HTTP ${res.status} from ${url}`
+    };
+  } catch {
+    return {
+      id: "dev_server",
+      label: "Dev server reachable",
+      status: "warn",
+      detail: `Start pnpm dev \u2014 could not reach ${url}`
+    };
+  }
+}
+function summarize(result) {
+  const total = result.checks.length;
+  const passed = result.passCount;
+  const label = result.failCount > 0 ? "nuvio not ready" : result.warnCount > 0 ? "nuvio partially ready" : "nuvio ready";
+  console.log(`
+Result: ${passed}/${total} passed \u2014 ${label}`);
+}
+async function runDoctor(opts) {
+  let scan;
+  try {
+    scan = scanProject(opts.cwd);
+  } catch (e) {
+    if (e instanceof PreflightError) {
+      console.error(e.message);
+      return 1;
+    }
+    throw e;
+  }
+  const { ctx, detectedLibraries, index } = scan;
+  const pkg = ctx.packageJson;
+  const projectName = String(pkg.name ?? "project");
+  const verification = verifyProject(
+    ctx.root,
+    ctx.packageJsonPath,
+    ctx.viteConfigPath
+  );
+  const checks = [
+    {
+      id: "deps_plugin",
+      label: "@nuvio/vite-plugin installed",
+      status: verification.deps === "OK" ? "pass" : "fail"
+    },
+    {
+      id: "deps_overlay",
+      label: "@nuvio/overlay installed",
+      status: verification.deps === "OK" ? "pass" : "fail"
+    },
+    {
+      id: "vite_plugin",
+      label: "vite.config contains nuvio()",
+      status: verification.vite === "OK" ? "pass" : "fail"
+    },
+    {
+      id: "optimize_deps",
+      label: "optimizeDeps.exclude includes @nuvio/overlay",
+      status: verification.optimizeDeps === "OK" ? "pass" : "fail",
+      detail: verification.optimizeDeps === "OK" && nuvioOverlayLinkKind(pkg) === "workspace" ? "workspace install \u2014 optional" : void 0
+    },
+    {
+      id: "overlay_css",
+      label: "main entry imports @nuvio/overlay/style.css",
+      status: verification.overlayCss === "OK" ? "pass" : "fail",
+      detail: verification.overlayCss === "OK" && nuvioOverlayLinkKind(pkg) === "workspace" ? "workspace install \u2014 optional" : void 0
+    },
+    {
+      id: "dev_shell",
+      label: "NuvioDevShell mounted in app",
+      status: verification.shell === "OK" ? "pass" : "fail"
+    },
+    {
+      id: "tailwind",
+      label: "Tailwind detected",
+      status: ctx.tailwindOk ? "pass" : "warn",
+      detail: ctx.tailwindOk ? void 0 : "Style edits may not apply visually without Tailwind"
+    },
+    {
+      id: "editable_hosts",
+      label: "At least one data-nuvio-id indexed",
+      status: index.entries.length > 0 ? "pass" : "fail",
+      detail: index.entries.length > 0 ? `${index.entries.length} host(s)` : "Run dev \u2192 Make Editable, or add ids manually"
+    }
+  ];
+  if (detectedLibraries.length > 0) {
+    checks.push({
+      id: "libraries",
+      label: "Component libraries detected",
+      status: "pass",
+      detail: detectedLibraries.join(", ")
+    });
+  }
+  if (index.duplicateErrors.length > 0) {
+    checks.push({
+      id: "duplicate_ids",
+      label: "No duplicate data-nuvio-id values",
+      status: "fail",
+      detail: `${index.duplicateErrors.length} duplicate id(s) \u2014 run nuvio scan`
+    });
+  } else {
+    checks.push({
+      id: "duplicate_ids",
+      label: "No duplicate data-nuvio-id values",
+      status: "pass"
+    });
+  }
+  if (opts.checkDevServer !== false) {
+    checks.push(await checkDevServerReachable(opts.devServerPort ?? 5173));
+  }
+  const passCount = checks.filter((c) => c.status === "pass").length;
+  const warnCount = checks.filter((c) => c.status === "warn").length;
+  const failCount = checks.filter((c) => c.status === "fail").length;
+  const result = {
+    projectName,
+    checks,
+    passCount,
+    warnCount,
+    failCount
+  };
+  const pm = detectPackageManager(ctx.root);
+  const telemetry = {
+    ...buildCliTelemetryProps(pm, ctx),
+    pass_count: passCount,
+    warn_count: warnCount,
+    fail_count: failCount,
+    ready: failCount === 0
+  };
+  captureCliEvent("doctor_run", telemetry);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return failCount > 0 ? 1 : 0;
+  }
+  console.log(`nuvio doctor \u2014 ${projectName}
+`);
+  for (const check of checks) {
+    const icon = check.status === "pass" ? "\u2705" : check.status === "warn" ? "\u26A0" : "\u274C";
+    const suffix = check.detail ? ` \u2014 ${check.detail}` : "";
+    console.log(`  ${icon} ${check.label}${suffix}`);
+  }
+  summarize(result);
+  return failCount > 0 ? 1 : 0;
+}
+
+// src/init.ts
+import { createInterface } from "readline";
+
+// src/install-packages.ts
+import { spawnSync } from "child_process";
+import { readFileSync as readFileSync8 } from "fs";
+function parseInstalledVersion(pkg, name) {
+  const dev = pkg.devDependencies;
+  const deps = pkg.dependencies;
+  const raw = dev?.[name] ?? deps?.[name];
+  if (!raw) return null;
+  return raw.replace(/^[\^~]/, "");
+}
+function packagesNeedInstall(packageJsonPath, targetVersion) {
+  const pkg = JSON.parse(readFileSync8(packageJsonPath, "utf8"));
+  for (const name of ["@nuvio/vite-plugin", "@nuvio/overlay"]) {
+    const v = parseInstalledVersion(pkg, name);
+    if (v !== targetVersion) return true;
+  }
+  return false;
+}
+function runInstall(root, pm, version) {
+  const cmd = installCommand(pm, version);
+  const result = spawnSync(cmd, {
+    cwd: root,
+    shell: true,
+    stdio: "inherit",
+    env: process.env
+  });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      message: `Install failed. Try manually:
+  ${cmd}`
+    };
+  }
+  return { ok: true };
+}
+
 // src/patch-starter-id.ts
+import * as t3 from "@babel/types";
+import { readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
 function patchFirstHeading(filePath) {
-  const source = readFileSync7(filePath, "utf8");
+  const source = readFileSync9(filePath, "utf8");
   let ast;
   try {
     ast = parseTs(source, filePath);
@@ -563,13 +1034,13 @@ function patchFirstHeading(filePath) {
     }
   });
   if (!patched) return { ok: false, error: "no h1/h2" };
-  writeFileSync4(filePath, printTs(ast, source), "utf8");
+  writeFileSync5(filePath, printTs(ast, source), "utf8");
   return { ok: true };
 }
 function patchStarterId(root) {
   const files = findHeadingFiles(root);
   for (const file of files) {
-    const source = readFileSync7(file, "utf8");
+    const source = readFileSync9(file, "utf8");
     if (!/<h[12][\s>]/.test(source) && !/<>[\s\S]*<h[12]/.test(source)) {
       try {
         const ast = parseTs(source, file);
@@ -608,18 +1079,13 @@ function createPlan(root, pm) {
   };
 }
 
-// src/version.ts
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-var NUVIO_VERSION = require2("../package.json").version;
-
 // src/write-nuvio-folder.ts
-import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
-import { dirname, join as join6 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
+import { dirname, join as join7 } from "path";
 import { fileURLToPath } from "url";
-var CLI_ROOT = join6(dirname(fileURLToPath(import.meta.url)), "..");
+var CLI_ROOT = join7(dirname(fileURLToPath(import.meta.url)), "..");
 function loadTemplate(name) {
-  return readFileSync8(join6(CLI_ROOT, "templates", name), "utf8");
+  return readFileSync10(join7(CLI_ROOT, "templates", name), "utf8");
 }
 function render(tpl, vars) {
   let out = tpl;
@@ -629,36 +1095,36 @@ function render(tpl, vars) {
   return out;
 }
 function writeNuvioFolder(opts) {
-  const dir = join6(opts.root, "nuvio");
+  const dir = join7(opts.root, "nuvio");
   const created = [];
-  mkdirSync(dir, { recursive: true });
+  mkdirSync2(dir, { recursive: true });
   const vars = {
     NUVIO_VERSION: opts.version,
     PM_RUN: opts.pmRun,
     FAILED_STEPS: opts.failedSteps.join(", ") || "(none)"
   };
-  const startHere = join6(dir, "START_HERE.md");
-  writeFileSync5(
+  const startHere = join7(dir, "START_HERE.md");
+  writeFileSync6(
     startHere,
     render(loadTemplate("START_HERE.md.tpl"), vars),
     "utf8"
   );
   created.push("nuvio/START_HERE.md");
-  const readme = join6(dir, "README.md");
-  writeFileSync5(
+  const readme = join7(dir, "README.md");
+  writeFileSync6(
     readme,
     render(loadTemplate("README.pointer.md.tpl"), vars),
     "utf8"
   );
   created.push("nuvio/README.md");
-  const agent = join6(dir, "AGENT.md");
+  const agent = join7(dir, "AGENT.md");
   if (!existsSync5(agent) || opts.forceAgent) {
-    writeFileSync5(agent, render(loadTemplate("AGENT.md.tpl"), vars), "utf8");
+    writeFileSync6(agent, render(loadTemplate("AGENT.md.tpl"), vars), "utf8");
     created.push("nuvio/AGENT.md");
   }
   if (opts.failedSteps.length > 0) {
-    const todo = join6(dir, "SETUP_TODO.md");
-    writeFileSync5(
+    const todo = join7(dir, "SETUP_TODO.md");
+    writeFileSync6(
       todo,
       render(loadTemplate("SETUP_TODO.md.tpl"), vars),
       "utf8"
@@ -668,194 +1134,6 @@ function writeNuvioFolder(opts) {
   return created;
 }
 
-// src/verify.ts
-import { readFileSync as readFileSync9 } from "fs";
-function verifyProject(root, packageJsonPath, viteConfigPath) {
-  const pkg = JSON.parse(readFileSync9(packageJsonPath, "utf8"));
-  const dev = pkg.devDependencies;
-  const depsOk = Boolean(dev?.["@nuvio/vite-plugin"]) && Boolean(dev?.["@nuvio/overlay"]);
-  const appFile = resolveAppFile(root);
-  const mainEntry = resolveMainEntry(root);
-  return {
-    deps: depsOk ? "OK" : "MISSING",
-    vite: viteConfigHasNuvio(viteConfigPath) ? "OK" : "TODO",
-    overlayCss: mainEntry && (mainHasOverlayStyles(mainEntry) || !overlayInstalledFromNpm(packageJsonPath)) ? "OK" : "TODO",
-    optimizeDeps: viteConfigHasOverlayOptimizeExclude(viteConfigPath) ? "OK" : "TODO",
-    shell: appFile && appHasDevShell(appFile) ? "OK" : "TODO",
-    starterId: projectHasPageTitleId(root) ? "OK" : "MISSING"
-  };
-}
-function printVerification(v) {
-  console.log("Verification:");
-  console.log(
-    `  devDependencies: @nuvio/vite-plugin, @nuvio/overlay \u2014 ${v.deps}`
-  );
-  console.log(`  vite.config: nuvio() \u2014 ${v.vite}`);
-  console.log(`  main.tsx: @nuvio/overlay/style.css \u2014 ${v.overlayCss}`);
-  console.log(`  vite.config: optimizeDeps exclude overlay \u2014 ${v.optimizeDeps}`);
-  console.log(`  App shell: NuvioDevShell \u2014 ${v.shell}`);
-  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;
@@ -889,14 +1167,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(
@@ -917,7 +1195,7 @@ 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(`
@@ -1017,7 +1295,7 @@ async function runInit(opts) {
         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)");
@@ -1101,14 +1379,162 @@ async function runInit(opts) {
   return plan.tier === "partial" || plan.tier === "full" ? 0 : 1;
 }
 
+// src/scan-cmd.ts
+function runScan(opts) {
+  let scan;
+  try {
+    scan = scanProject(opts.cwd);
+  } catch (e) {
+    if (e instanceof PreflightError) {
+      console.error(e.message);
+      return 1;
+    }
+    throw e;
+  }
+  const { ctx, detectedLibraries, index } = scan;
+  const projectName = String(ctx.packageJson.name ?? "project");
+  const hosts = index.entries.map((entry) => ({
+    id: entry.id,
+    file: relPath(ctx.root, entry.file),
+    line: entry.line,
+    column: entry.column,
+    libraryHint: entry.libraryHint,
+    classNameMode: entry.classNameMode
+  }));
+  const result = {
+    projectName,
+    hosts,
+    hostCount: hosts.length,
+    duplicateErrors: index.duplicateErrors.map((dup) => ({
+      id: dup.id,
+      occurrences: dup.occurrences.map((o) => ({
+        file: relPath(ctx.root, o.file),
+        line: o.line
+      }))
+    })),
+    detectedLibraries,
+    scannedFileCount: index.scannedFileCount
+  };
+  const pm = detectPackageManager(ctx.root);
+  const telemetry = {
+    ...buildCliTelemetryProps(pm, ctx),
+    host_count: result.hostCount,
+    duplicate_count: result.duplicateErrors.length,
+    library_count: detectedLibraries.length
+  };
+  captureCliEvent("scan_run", telemetry);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.duplicateErrors.length > 0 ? 1 : 0;
+  }
+  console.log(`nuvio scan \u2014 ${result.hostCount} editable host(s)
+`);
+  for (const host of hosts) {
+    console.log(
+      `  ${host.id.padEnd(28)} ${host.file}:${host.line}`
+    );
+  }
+  if (result.duplicateErrors.length > 0) {
+    console.log("");
+    for (const dup of result.duplicateErrors) {
+      const places = dup.occurrences.map((o) => `${o.file}:${o.line}`).join(", ");
+      console.log(`  \u274C duplicate id: ${dup.id} (${places}) \u2014 fix before apply`);
+    }
+  }
+  if (detectedLibraries.length > 0) {
+    console.log(`
+  Libraries: ${detectedLibraries.join(", ")}`);
+  }
+  if (result.hostCount === 0) {
+    console.log(
+      "\n  No hosts found \u2014 use Make Editable in the browser or add data-nuvio-id manually."
+    );
+  }
+  return result.duplicateErrors.length > 0 ? 1 : 0;
+}
+
+// src/stats.ts
+import { readRuntimeVersions } from "@nuvio/vite-plugin/scan";
+function runStats(opts) {
+  let scan;
+  try {
+    scan = scanProject(opts.cwd);
+  } catch (e) {
+    if (e instanceof PreflightError) {
+      console.error(e.message);
+      return 1;
+    }
+    throw e;
+  }
+  const { ctx, detectedLibraries, index } = scan;
+  const projectName = String(ctx.packageJson.name ?? "project");
+  const taggedFiles = new Set(
+    index.entries.map((e) => relPath(ctx.root, e.file))
+  ).size;
+  const classNameModes = aggregateClassNameModes(index.entries);
+  const tableHosts = index.entries.filter(isTableHost).length;
+  const versions = readRuntimeVersions(ctx.root);
+  const result = {
+    projectName,
+    editableHosts: index.entries.length,
+    taggedFiles,
+    scannedFiles: index.scannedFileCount,
+    duplicateIds: index.duplicateErrors.length,
+    tableHosts,
+    detectedLibraries,
+    tailwindVersion: versions.tailwindVersion,
+    classNameModes
+  };
+  const pm = detectPackageManager(ctx.root);
+  const telemetry = {
+    ...buildCliTelemetryProps(pm, ctx),
+    editable_hosts: result.editableHosts,
+    tagged_files: result.taggedFiles,
+    duplicate_ids: result.duplicateIds,
+    table_hosts: result.tableHosts,
+    library_count: detectedLibraries.length
+  };
+  captureCliEvent("stats_run", telemetry);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  console.log("nuvio stats\n");
+  console.log(`  Editable hosts:     ${result.editableHosts}`);
+  console.log(`  Tagged files:       ${result.taggedFiles}`);
+  console.log(`  Files scanned:      ${result.scannedFiles}`);
+  console.log(
+    `  Libraries detected: ${result.detectedLibraries.length > 0 ? result.detectedLibraries.join(", ") : "none"}`
+  );
+  console.log(`  Table hosts:        ${result.tableHosts}`);
+  console.log(`  Duplicate ids:      ${result.duplicateIds}`);
+  if (result.tailwindVersion) {
+    console.log(`  Tailwind version:   ${result.tailwindVersion}`);
+  }
+  const modeParts = Object.entries(result.classNameModes).sort(([a], [b]) => a.localeCompare(b)).map(([mode, count]) => `${mode} ${count}`);
+  if (modeParts.length > 0) {
+    console.log(`  Class modes:        ${modeParts.join(", ")}`);
+  }
+  return 0;
+}
+
 // src/cli.ts
 function printHelp() {
-  console.log(`nuvio \u2014 Nuvio CLI
+  console.log(`nuvio \u2014 CLI for React + Vite
 
 Usage:
   nuvio init [options]
+  nuvio doctor [options]
+  nuvio scan [options]
+  nuvio stats [options]
+
+Common options:
+  --cwd <path>          Project root (default: current directory)
+  --json                Machine-readable output (doctor, scan, stats)
+  --verbose             Show error stacks
+  -h, --help            Show help
 
-Options:
+Init options:
   --yes                 Skip confirmation
   --no-install          Patch files only; do not run package manager install
   --dry-run             Show plan only (still prompts unless --yes / CI)
@@ -1116,16 +1542,18 @@ Options:
   --strict              Fail if Tailwind is not detected
   --skip-tailwind-check Do not warn when Tailwind is missing
   --force-agent         Overwrite nuvio/AGENT.md
-  --cwd <path>          Project root (default: current directory)
-  --verbose             Show error stacks
-  -h, --help            Show help
 
-Example:
-  pnpm dlx @nuvio/cli init
+Doctor options:
+  --skip-dev-server     Skip localhost dev-server health check
+
+Examples:
   pnpm dlx @nuvio/cli init --yes
+  pnpm dlx @nuvio/cli doctor
+  pnpm dlx @nuvio/cli scan --json
+  pnpm dlx @nuvio/cli stats
 `);
 }
-function parseArgs(argv) {
+function parseInitArgs(argv) {
   const args = argv.slice(2);
   let command = null;
   const opts = { cwd: process.cwd() };
@@ -1158,30 +1586,98 @@ function parseArgs(argv) {
   }
   return { command, opts, help };
 }
-async function runCli(argv) {
-  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;
+function parseProjectCommandArgs(argv, command) {
+  const args = argv.slice(2);
+  const common = { cwd: process.cwd() };
+  const doctor = { ...common };
+  let help = false;
+  let i = args[0] === command ? 1 : 0;
+  for (; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      help = true;
+      continue;
+    }
+    if (arg === "--json") {
+      common.json = true;
+      doctor.json = true;
+    } else if (arg === "--verbose") {
+      common.verbose = true;
+      doctor.verbose = true;
+    } else if (arg === "--cwd") {
+      const cwd = resolve(args[++i] ?? ".");
+      common.cwd = cwd;
+      doctor.cwd = cwd;
+    } else if (arg === "--skip-dev-server") {
+      doctor.skipDevServer = true;
+    } else if (arg.startsWith("-")) {
+      console.error(`Unknown option: ${arg}`);
+      help = true;
+    }
   }
+  return { command, common, doctor, help };
+}
+async function runCli(argv) {
+  registerTelemetrySignalHandlers();
+  const rawCommand = argv[2] ?? null;
+  const isProjectCmd = rawCommand === "doctor" || rawCommand === "scan" || rawCommand === "stats";
+  let help = false;
+  let command = rawCommand;
+  let initOpts = { cwd: process.cwd() };
+  let commonOpts = { cwd: process.cwd() };
+  let doctorOpts = { cwd: process.cwd() };
+  if (isProjectCmd) {
+    const parsed = parseProjectCommandArgs(argv, rawCommand);
+    help = parsed.help;
+    command = parsed.command;
+    commonOpts = parsed.common;
+    doctorOpts = parsed.doctor;
+  } else {
+    const parsed = parseInitArgs(argv);
+    help = parsed.help;
+    command = parsed.command;
+    initOpts = parsed.opts;
+  }
+  const cwd = isProjectCmd ? commonOpts.cwd : initOpts.cwd;
+  captureCliInvoked(
+    resolveCliInvokedCommand(help, command),
+    isProjectCmd ? void 0 : initOpts.pm
+  );
   try {
-    return await runInit(opts);
+    if (help) {
+      printHelp();
+      return 0;
+    }
+    if (!command) {
+      printHelp();
+      return 1;
+    }
+    switch (command) {
+      case "init":
+        return await runInit(initOpts);
+      case "doctor":
+        return await runDoctor({
+          cwd: doctorOpts.cwd,
+          json: doctorOpts.json,
+          checkDevServer: !doctorOpts.skipDevServer
+        });
+      case "scan":
+        return runScan({ cwd: commonOpts.cwd, json: commonOpts.json });
+      case "stats":
+        return runStats({ cwd: commonOpts.cwd, json: commonOpts.json });
+      default:
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        return 1;
+    }
   } catch (e) {
-    const pm = detectPackageManager(opts.cwd, opts.pm);
+    const pm = detectPackageManager(cwd, initOpts.pm);
     captureCliEvent("nuvio_init_failed", {
       ...buildCliTelemetryProps(pm),
       error_code: "unexpected_error"
     });
-    if (opts.verbose) console.error(e);
+    const verbose = isProjectCmd ? commonOpts.verbose : initOpts.verbose;
+    if (verbose) console.error(e);
     else console.error("Something went wrong. Run with --verbose for details.");
     return 2;
   } finally {