@nuvio/cli 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Nuvio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @nuvio/cli
+
+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).

package/dist/cli-entry.js

@@ -0,0 +1,851 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { resolve } from "path";
+
+// src/init.ts
+import { createInterface } from "readline";
+
+// src/detect-project.ts
+import { existsSync, readFileSync } from "fs";
+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.",
+  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).'
+};
+
+// src/detect-project.ts
+var VITE_CONFIGS = [
+  "vite.config.ts",
+  "vite.config.js",
+  "vite.config.mts",
+  "vite.config.mjs"
+];
+var PreflightError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PreflightError";
+  }
+};
+function hasDep(pkg, name) {
+  const deps = pkg.dependencies;
+  const dev = pkg.devDependencies;
+  return Boolean(deps?.[name] ?? dev?.[name]);
+}
+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 text = readFileSync(p, "utf8");
+    if (text.includes("@tailwind") || text.includes('@import "tailwindcss"') || text.includes("@import 'tailwindcss'")) {
+      return true;
+    }
+  }
+  return false;
+}
+function detectProject(root) {
+  const packageJsonPath = join(root, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    throw new PreflightError(MSG.noPackageJson);
+  }
+  const packageJson = JSON.parse(
+    readFileSync(packageJsonPath, "utf8")
+  );
+  if (packageJson.name === "@nuvio/cli") {
+    throw new PreflightError(MSG.cliPackage);
+  }
+  if (packageJson.name === "nuvio" && packageJson.private === true) {
+    throw new PreflightError(MSG.monorepoRoot);
+  }
+  let viteConfigPath = "";
+  let viteConfigName = "";
+  for (const name of VITE_CONFIGS) {
+    const p = join(root, name);
+    if (existsSync(p)) {
+      viteConfigPath = p;
+      viteConfigName = name;
+      break;
+    }
+  }
+  if (!viteConfigPath) {
+    throw new PreflightError(MSG.noVite);
+  }
+  if (!hasDep(packageJson, "react")) {
+    throw new PreflightError(MSG.noReact);
+  }
+  if (!hasDep(packageJson, "vite")) {
+    throw new PreflightError(MSG.noViteDep);
+  }
+  const tailwindOk = detectTailwind(root, packageJson);
+  return {
+    root,
+    packageJsonPath,
+    packageJson,
+    viteConfigPath,
+    viteConfigName,
+    tailwindOk,
+    tailwindWarn: !tailwindOk
+  };
+}
+
+// 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";
+}
+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/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(/^[\^~]/, "");
+}
+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 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/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/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-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;
+}
+function hasNuvioPluginCall(ast) {
+  let found = false;
+  babel_traverse_default(ast, {
+    CallExpression(path) {
+      if (t.isIdentifier(path.node.callee, { name: "nuvio" })) found = true;
+    }
+  });
+  return found;
+}
+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;
+    }
+  });
+  return patched;
+}
+function patchViteConfigFile(filePath) {
+  const source = readFileSync3(filePath, "utf8");
+  let ast;
+  try {
+    ast = parseTs(source, filePath);
+  } catch {
+    return { ok: false, error: "parse failed" };
+  }
+  if (hasNuvioImport(ast) && hasNuvioPluginCall(ast)) {
+    return { ok: true, skipped: true };
+  }
+  if (!hasNuvioImport(ast)) {
+    ast.program.body.unshift(
+      t.importDeclaration(
+        [t.importSpecifier(t.identifier("nuvio"), t.identifier("nuvio"))],
+        t.stringLiteral("@nuvio/vite-plugin")
+      )
+    );
+  }
+  if (!hasNuvioPluginCall(ast)) {
+    if (!appendNuvioPlugin(ast)) {
+      return { ok: false, error: "no static plugins array" };
+    }
+  }
+  writeFileSync(filePath, printTs(ast, source), "utf8");
+  return { ok: true };
+}
+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);
+  }
+}
+
+// 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",
+  "src/main.tsx",
+  "src/main.jsx"
+];
+function resolveAppFile(root) {
+  for (const rel of APP_CANDIDATES) {
+    const p = join3(root, rel);
+    if (existsSync3(p)) return p;
+  }
+  return null;
+}
+function hasOverlayImport(ast) {
+  let found = false;
+  babel_traverse_default(ast, {
+    ImportDeclaration(path) {
+      if (path.node.source.value === "@nuvio/overlay") found = true;
+    }
+  });
+  return found;
+}
+function hasDevShell(ast) {
+  let found = false;
+  babel_traverse_default(ast, {
+    JSXElement(path) {
+      const name = path.node.openingElement.name;
+      if (t2.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);
+  return null;
+}
+var devShellElement = t2.jsxElement(
+  t2.jsxOpeningElement(t2.jsxIdentifier("NuvioDevShell"), [], true),
+  null,
+  [],
+  true
+);
+function appendDevShell(ast) {
+  let patched = false;
+  babel_traverse_default(ast, {
+    ReturnStatement(path) {
+      const jsx = unwrapJsx(path.node.argument);
+      if (!jsx) return;
+      if (t2.isJSXFragment(jsx)) {
+        jsx.children.push(t2.jsxText("\n      "));
+        jsx.children.push(devShellElement);
+        patched = true;
+      } else {
+        path.node.argument = t2.jsxFragment(
+          t2.jsxOpeningFragment(),
+          t2.jsxClosingFragment(),
+          [jsx, t2.jsxText("\n      "), devShellElement]
+        );
+        patched = true;
+      }
+    }
+  });
+  return patched;
+}
+function patchAppRootFile(filePath) {
+  const source = readFileSync4(filePath, "utf8");
+  let ast;
+  try {
+    ast = parseTs(source, filePath);
+  } catch {
+    return { ok: false, error: "parse failed" };
+  }
+  if (hasOverlayImport(ast) && hasDevShell(ast)) {
+    return { ok: true, skipped: true };
+  }
+  if (!hasOverlayImport(ast)) {
+    ast.program.body.unshift(
+      t2.importDeclaration(
+        [
+          t2.importSpecifier(
+            t2.identifier("NuvioDevShell"),
+            t2.identifier("NuvioDevShell")
+          )
+        ],
+        t2.stringLiteral("@nuvio/overlay")
+      )
+    );
+  }
+  if (!hasDevShell(ast) && !appendDevShell(ast)) {
+    return { ok: false, error: "no JSX return to patch" };
+  }
+  writeFileSync2(filePath, printTs(ast, source), "utf8");
+  return { ok: true };
+}
+function appHasDevShell(filePath) {
+  if (!existsSync3(filePath)) return false;
+  const source = readFileSync4(filePath, "utf8");
+  try {
+    const ast = parseTs(source, filePath);
+    return hasOverlayImport(ast) && hasDevShell(ast);
+  } catch {
+    return /NuvioDevShell/.test(source);
+  }
+}
+
+// src/patch-starter-id.ts
+import * as t3 from "@babel/types";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
+
+// src/scan-ids.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { join as join4 } from "path";
+import fg from "fast-glob";
+var ID_GLOB = ["src/**/*.{tsx,jsx}"];
+function projectHasPageTitleId(root) {
+  const files = fg.sync(ID_GLOB, { cwd: root, absolute: true });
+  for (const file of files) {
+    const text = readFileSync5(file, "utf8");
+    if (/data-nuvio-id=["']page\.title["']/.test(text)) {
+      return true;
+    }
+  }
+  return false;
+}
+function findHeadingFiles(root) {
+  const files = fg.sync(ID_GLOB, { cwd: root, absolute: true });
+  const ordered = [
+    join4(root, "src/App.tsx"),
+    join4(root, "src/App.jsx"),
+    ...files.filter(
+      (f) => !f.endsWith("App.tsx") && !f.endsWith("App.jsx")
+    )
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const f of ordered) {
+    if (!seen.has(f) && files.includes(f)) {
+      seen.add(f);
+      out.push(f);
+    }
+  }
+  for (const f of files) {
+    if (!seen.has(f)) out.push(f);
+  }
+  return out;
+}
+
+// src/patch-starter-id.ts
+function patchFirstHeading(filePath) {
+  const source = readFileSync6(filePath, "utf8");
+  let ast;
+  try {
+    ast = parseTs(source, filePath);
+  } catch {
+    return { ok: false, error: "parse failed" };
+  }
+  let patched = false;
+  babel_traverse_default(ast, {
+    JSXOpeningElement(path) {
+      if (patched) return;
+      const name = path.node.name;
+      if (!t3.isJSXIdentifier(name)) return;
+      if (name.name !== "h1" && name.name !== "h2") return;
+      for (const attr of path.node.attributes) {
+        if (t3.isJSXAttribute(attr) && t3.isJSXIdentifier(attr.name, { name: "data-nuvio-id" })) {
+          return;
+        }
+      }
+      path.node.attributes.push(
+        t3.jsxAttribute(
+          t3.jsxIdentifier("data-nuvio-id"),
+          t3.stringLiteral("page.title")
+        )
+      );
+      patched = true;
+    }
+  });
+  if (!patched) return { ok: false, error: "no h1/h2" };
+  writeFileSync3(filePath, printTs(ast, source), "utf8");
+  return { ok: true };
+}
+function patchStarterId(root) {
+  const files = findHeadingFiles(root);
+  for (const file of files) {
+    const source = readFileSync6(file, "utf8");
+    if (!/<h[12][\s>]/.test(source) && !/<>[\s\S]*<h[12]/.test(source)) {
+      try {
+        const ast = parseTs(source, file);
+        let has = false;
+        babel_traverse_default(ast, {
+          JSXOpeningElement(path) {
+            const name = path.node.name;
+            if (t3.isJSXIdentifier(name) && (name.name === "h1" || name.name === "h2"))
+              has = true;
+          }
+        });
+        if (!has) continue;
+      } catch {
+        continue;
+      }
+    }
+    const outcome = patchFirstHeading(file);
+    if (outcome.ok) return { outcome, file };
+  }
+  return { outcome: { ok: false, error: "no heading" } };
+}
+
+// src/plan.ts
+function createPlan(root, pm) {
+  const pmRun = pm === "pnpm" ? "pnpm dev" : pm === "yarn" ? "yarn dev" : pm === "bun" ? "bun run dev" : "npm run dev";
+  return {
+    root,
+    pm,
+    pmRun,
+    installCommand: "",
+    modify: [],
+    create: [],
+    warnings: [],
+    tier: "full",
+    failedSteps: []
+  };
+}
+
+// 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 existsSync4, mkdirSync, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+import { dirname, join as join5 } from "path";
+import { fileURLToPath } from "url";
+var CLI_ROOT = join5(dirname(fileURLToPath(import.meta.url)), "..");
+function loadTemplate(name) {
+  return readFileSync7(join5(CLI_ROOT, "templates", name), "utf8");
+}
+function render(tpl, vars) {
+  let out = tpl;
+  for (const [key, value] of Object.entries(vars)) {
+    out = out.replaceAll(`{{${key}}}`, value);
+  }
+  return out;
+}
+function writeNuvioFolder(opts) {
+  const dir = join5(opts.root, "nuvio");
+  const created = [];
+  mkdirSync(dir, { recursive: true });
+  const vars = {
+    NUVIO_VERSION: opts.version,
+    PM_RUN: opts.pmRun,
+    FAILED_STEPS: opts.failedSteps.join(", ") || "(none)"
+  };
+  const startHere = join5(dir, "START_HERE.md");
+  writeFileSync4(
+    startHere,
+    render(loadTemplate("START_HERE.md.tpl"), vars),
+    "utf8"
+  );
+  created.push("nuvio/START_HERE.md");
+  const readme = join5(dir, "README.md");
+  writeFileSync4(
+    readme,
+    render(loadTemplate("README.pointer.md.tpl"), vars),
+    "utf8"
+  );
+  created.push("nuvio/README.md");
+  const agent = join5(dir, "AGENT.md");
+  if (!existsSync4(agent) || opts.forceAgent) {
+    writeFileSync4(agent, render(loadTemplate("AGENT.md.tpl"), vars), "utf8");
+    created.push("nuvio/AGENT.md");
+  }
+  if (opts.failedSteps.length > 0) {
+    const todo = join5(dir, "SETUP_TODO.md");
+    writeFileSync4(
+      todo,
+      render(loadTemplate("SETUP_TODO.md.tpl"), vars),
+      "utf8"
+    );
+    created.push("nuvio/SETUP_TODO.md");
+  }
+  return created;
+}
+
+// src/verify.ts
+import { readFileSync as readFileSync8 } from "fs";
+function verifyProject(root, packageJsonPath, viteConfigPath) {
+  const pkg = JSON.parse(readFileSync8(packageJsonPath, "utf8"));
+  const dev = pkg.devDependencies;
+  const depsOk = Boolean(dev?.["@nuvio/vite-plugin"]) && Boolean(dev?.["@nuvio/overlay"]);
+  const appFile = resolveAppFile(root);
+  return {
+    deps: depsOk ? "OK" : "MISSING",
+    vite: viteConfigHasNuvio(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(`  App shell: NuvioDevShell \u2014 ${v.shell}`);
+  console.log(`  Starter id page.title \u2014 ${v.starterId}`);
+}
+
+// src/init.ts
+function isAutoYes(opts) {
+  if (opts.yes) return true;
+  if (process.env.CI === "true") return true;
+  return !process.stdin.isTTY;
+}
+async function confirm(plan) {
+  console.log("\nPlanned changes:");
+  for (const f of plan.modify) console.log(`  modify: ${f}`);
+  for (const f of plan.create) console.log(`  create: ${f}`);
+  if (plan.warnings.length) {
+    console.log("\nWarnings:");
+    for (const w of plan.warnings) console.log(`  \u26A0 ${w}`);
+  }
+  console.log(`
+Install: ${plan.installCommand || "(skip)"}`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve2) => {
+    rl.question("\nProceed? [y/N] ", (answer) => {
+      rl.close();
+      resolve2(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+function computeTier(installOk, viteOk, appOk, starterOk) {
+  if (!installOk) return "failed";
+  if (!appOk) return "failed";
+  if (!viteOk || !starterOk) return "partial";
+  return "full";
+}
+function printSuccess(plan, checks) {
+  if (checks.install) {
+    console.log(
+      `\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");
+  else console.log("\u26A0 App shell \u2014 see nuvio/SETUP_TODO.md");
+  if (checks.starter) {
+    console.log(
+      `\u2705 Starter editable area: page.title${checks.starterFile ? ` (${checks.starterFile})` : ""}`
+    );
+  } else {
+    console.log(`\u26A0 ${MSG.noHeading}`);
+  }
+  console.log("\u2705 Start here: nuvio/START_HERE.md");
+  console.log("\u2705 Agent guide: nuvio/AGENT.md");
+  console.log(`
+Next:
+  ${plan.pmRun}
+`);
+  console.log("Open localhost \u2192 Edit on \u2192 click the starter element.");
+  if (plan.tier === "partial" && plan.failedSteps.length > 0) {
+    console.log(`
+${MSG.partialHelp}`);
+  } else if (plan.tier === "partial") {
+    console.log(
+      "\nNuvio helped you as far as it safely could. See warnings above."
+    );
+  }
+}
+async function runInit(opts) {
+  const root = opts.cwd;
+  let project;
+  try {
+    project = detectProject(root);
+  } catch (e) {
+    if (e instanceof PreflightError) {
+      console.error(e.message);
+      return 1;
+    }
+    if (opts.verbose) console.error(e);
+    console.error("Something went wrong. Run with --verbose for details.");
+    return 2;
+  }
+  const pm = detectPackageManager(root, opts.pm);
+  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);
+      return 1;
+    }
+    plan.warnings.push(msg);
+  }
+  const appFile = resolveAppFile(root);
+  if (appFile) plan.modify.push(appFile.replace(`${root}/`, ""));
+  plan.modify.push(project.viteConfigName);
+  plan.create.push(
+    "nuvio/START_HERE.md",
+    "nuvio/README.md",
+    "nuvio/AGENT.md"
+  );
+  if (opts.dryRun) {
+    console.log("Dry run \u2014 no files changed.\n");
+    for (const f of plan.modify) console.log(`  would modify: ${f}`);
+    for (const f of plan.create) console.log(`  would create: ${f}`);
+    if (plan.warnings.length) {
+      for (const w of plan.warnings) console.log(`  would warn: ${w}`);
+    }
+    console.log(`  would run: ${plan.installCommand}`);
+    return 0;
+  }
+  if (!isAutoYes(opts)) {
+    const ok = await confirm(plan);
+    if (!ok) {
+      console.log("Cancelled.");
+      return 1;
+    }
+  }
+  let installOk = true;
+  if (!opts.noInstall) {
+    if (packagesNeedInstall(project.packageJsonPath, NUVIO_VERSION)) {
+      const result = runInstall(root, pm, NUVIO_VERSION);
+      if (!result.ok) {
+        console.error(result.message ?? "Install failed.");
+        return 1;
+      }
+    } else {
+      console.log("\u2705 Nuvio packages already installed");
+    }
+  } else {
+    console.log("(skipped install \u2014 --no-install)");
+    installOk = true;
+  }
+  let viteOk = false;
+  const viteResult = patchViteConfigFile(project.viteConfigPath);
+  if (viteResult.ok) {
+    viteOk = true;
+  } else {
+    plan.failedSteps.push(`vite (${viteResult.error ?? "unknown"})`);
+    plan.warnings.push(`Could not patch ${project.viteConfigName}`);
+  }
+  let appOk = false;
+  if (appFile) {
+    const appResult = patchAppRootFile(appFile);
+    if (appResult.ok) {
+      appOk = true;
+    } else {
+      plan.failedSteps.push(`app (${appResult.error ?? "unknown"})`);
+      plan.warnings.push(`Could not patch ${appFile}`);
+    }
+  } else {
+    plan.failedSteps.push("app (no App.tsx/main.tsx)");
+  }
+  let starterOk = false;
+  let starterFile;
+  if (!projectHasPageTitleId(root)) {
+    const { outcome, file } = patchStarterId(root);
+    if (outcome.ok) {
+      starterOk = true;
+      starterFile = file?.replace(`${root}/`, "");
+      if (file) plan.modify.push(starterFile);
+    } else {
+      plan.warnings.push(MSG.noHeading);
+    }
+  } else {
+    starterOk = true;
+    console.log("\u2705 Starter id page.title already present");
+  }
+  writeNuvioFolder({
+    root,
+    version: NUVIO_VERSION,
+    pmRun: plan.pmRun,
+    failedSteps: plan.failedSteps,
+    forceAgent: opts.forceAgent
+  });
+  plan.tier = computeTier(installOk, viteOk, appOk, starterOk);
+  console.log("");
+  printSuccess(plan, {
+    install: installOk,
+    vite: viteOk,
+    app: appOk,
+    starter: starterOk,
+    starterFile
+  });
+  const verification = verifyProject(
+    root,
+    project.packageJsonPath,
+    project.viteConfigPath
+  );
+  printVerification(verification);
+  if (plan.tier === "failed") return 1;
+  return plan.tier === "partial" || plan.tier === "full" ? 0 : 1;
+}
+
+// src/cli.ts
+function printHelp() {
+  console.log(`nuvio \u2014 Nuvio CLI
+
+Usage:
+  nuvio init [options]
+
+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)
+  --pm <pnpm|npm|yarn|bun>  Force package manager
+  --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
+  pnpm dlx @nuvio/cli init --yes
+`);
+}
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let command = null;
+  const opts = { cwd: process.cwd() };
+  let help = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      help = true;
+      continue;
+    }
+    if (!command && !arg.startsWith("-")) {
+      command = arg;
+      continue;
+    }
+    if (arg === "--yes") opts.yes = true;
+    else if (arg === "--no-install") opts.noInstall = true;
+    else if (arg === "--dry-run") opts.dryRun = true;
+    else if (arg === "--strict") opts.strict = true;
+    else if (arg === "--skip-tailwind-check") opts.skipTailwindCheck = true;
+    else if (arg === "--force-agent") opts.forceAgent = true;
+    else if (arg === "--verbose") opts.verbose = true;
+    else if (arg === "--pm") {
+      opts.pm = args[++i];
+    } else if (arg === "--cwd") {
+      opts.cwd = resolve(args[++i] ?? ".");
+    } else if (arg.startsWith("-")) {
+      console.error(`Unknown option: ${arg}`);
+      help = true;
+    }
+  }
+  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;
+  }
+  try {
+    return await runInit(opts);
+  } catch (e) {
+    if (opts.verbose) console.error(e);
+    else console.error("Something went wrong. Run with --verbose for details.");
+    return 2;
+  }
+}
+
+// src/cli-entry.ts
+var code = await runCli(process.argv);
+process.exit(code);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@nuvio/cli",
+  "version": "0.5.1",
+  "description": "Nuvio CLI: one-command Vite + React onboarding (nuvio init).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ehah/Nuvio.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "nuvio",
+    "vite",
+    "cli",
+    "onboarding",
+    "devtools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "bin": {
+    "nuvio": "./dist/cli-entry.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.26.9",
+    "@babel/parser": "^7.26.9",
+    "@babel/traverse": "^7.26.9",
+    "@babel/types": "^7.26.9",
+    "fast-glob": "^3.3.3"
+  },
+  "devDependencies": {
+    "@types/babel__generator": "^7.6.8",
+    "@types/babel__traverse": "^7.20.7",
+    "@types/node": "^22.13.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.6"
+  },
+  "scripts": {
+    "build": "tsup src/cli-entry.ts --format esm --clean --external @babel/parser --external @babel/traverse --external @babel/generator --external @babel/types --external fast-glob",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/templates/AGENT.md.tpl

@@ -0,0 +1,27 @@
+<!-- nuvio-cli-template: 1 -->
+# Nuvio agent instructions
+
+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:
+
+1. Do **not** change unrelated files.
+2. Add **string literal** `data-nuvio-id="region.name"` on JSX elements they should click in the browser.
+3. Keep `className="..."` as a **string literal** on that same tag when they need Tailwind class patches (avoid `cn(...)` on the patch target).
+4. Never use `{condition ? "id" : undefined}` for `data-nuvio-id` — use a string literal on the branch they edit.
+
+**Card pattern:**
+- `metric.orders.card` (container)
+- `metric.orders.label`
+- `metric.orders.value`
+
+**Table pattern:**
+- `orders.section`, `orders.title`
+- `orders.header.products` (column headers)
+- `orders.row.${id}.nameText` (row text — template literal id is OK for rows)
+
+**After instrumentation:** user runs `{{PM_RUN}}`, Edit on, Preview Changes, Apply to Code.
+
+If Vite or shell wiring is missing, see `nuvio/SETUP_TODO.md` or run `pnpm dlx @nuvio/cli@{{NUVIO_VERSION}} init`.
+
+Human quick path: `nuvio/START_HERE.md`.

package/templates/README.pointer.md.tpl

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

package/templates/SETUP_TODO.md.tpl

@@ -0,0 +1,27 @@
+<!-- nuvio-cli-template: 1 -->
+# Nuvio setup — manual steps
+
+@nuvio/cli could not safely patch: {{FAILED_STEPS}}
+
+## Vite (if needed)
+
+Add to `vite.config.ts`:
+
+```ts
+import { nuvio } from "@nuvio/vite-plugin";
+// inside defineConfig:
+plugins: [react(), nuvio()],
+resolve: { dedupe: ["react", "react-dom"] },
+```
+
+## App shell (if needed)
+
+```tsx
+import { NuvioDevShell } from "@nuvio/overlay";
+// inside root component return:
+<NuvioDevShell />
+```
+
+## Starter id (if needed)
+
+Add to one visible heading: `data-nuvio-id="page.title"`

package/templates/START_HERE.md.tpl

@@ -0,0 +1,16 @@
+<!-- nuvio-cli-template: 1 -->
+# Start here — Nuvio in this project
+
+Installed with @nuvio/cli@{{NUVIO_VERSION}}.
+
+**Run:** {{PM_RUN}}
+
+**Then:**
+1. Open the localhost URL from the terminal
+2. Turn **Edit** on (Nuvio chip)
+3. Click the starter element (usually the page title — id `page.title`)
+4. **Preview Changes** → **Apply to Code**
+
+**More UI (cards, tables, nav):** ask your AI agent to read `nuvio/AGENT.md` and add `data-nuvio-id` attributes.
+
+**Manual setup:** https://github.com/ehah/Nuvio/blob/v{{NUVIO_VERSION}}/docs/nuvioUser.md