virastack 0.0.1 → 1.0.0

package/src/i18n.js

@@ -0,0 +1,231 @@
+/**
+ * Minimal i18n dictionary for the ViraStack Start.
+ * Default locale is English; pass --tr to switch to Turkish.
+ */
+
+const dictionaries = {
+  en: {
+    cancel: "Operation cancelled.",
+    "telemetry.notice":
+      "ViraStack collects anonymous usage data (template, i18n choice, selected tools) to improve the CLI. No personal data is ever collected. Disable anytime with --telemetry-disable.",
+
+    "projectName.message": "What is your project named?",
+    "projectName.placeholder": "virastack-app",
+    "projectName.errorEmpty":
+      'Please enter a project name, or "." to use the current directory.',
+    "projectName.errorInvalid":
+      "Please enter a valid npm package name (lowercase letters, numbers, dashes).",
+    "projectName.errorNonInteractive":
+      "Project name is required in non-interactive mode. Pass a name, use --name, or \".\".",
+    "projectName.confirmNonEmptyDir":
+      'Directory "{dir}" is not empty. Continue anyway?',
+
+    "template.message": "Which template would you like to use?",
+    "template.nextjs.label": "Next.js App Router",
+    "template.nextjs.hint": "Recommended",
+    "template.tanstack.label": "TanStack Start",
+    "template.tanstack.hint": "File-based routing + SSR",
+    "template.tanstack.notReady":
+      "The TanStack Start template isn't available in this install. Using Next.js instead.",
+    "template.errorInvalid":
+      'Unknown template "{template}". Available templates: nextjs, tanstack.',
+
+    "i18n.message": "Would you like multi-language (i18n) support?",
+    "i18n.active": "Yes",
+    "i18n.inactive": "No",
+    "i18n.notReady":
+      "The multi-language (i18n) template isn't ready for this stack yet. Using the standard template instead.",
+
+    "tools.message": "Which ViraStack tools would you like to include?",
+    "tools.mask.label": "@virastack/mask",
+    "tools.mask.hint": "Headless input formatter",
+    "tools.password.label": "@virastack/password",
+    "tools.password.hint": "Password visibility toggle",
+    "tools.ai.label": "@virastack/ai",
+    "tools.ai.hint": "AI rules for Cursor & Claude",
+
+    "scaffold.copying": "Creating project files...",
+    "scaffold.copyDone": "Project files created.",
+    "scaffold.gitInit": "Initializing git repository...",
+    "scaffold.gitInitDone": "Git repository initialized.",
+    "scaffold.gitInitSkipped": "Skipped git initialization.",
+    "scaffold.installing": "Installing dependencies with {pm}...",
+    "scaffold.installDone": "Dependencies installed.",
+    "scaffold.installFailed":
+      "Failed to install dependencies.",
+    "scaffold.skipInstall":
+      "Skipping dependency install (--skip-install).",
+    "scaffold.offline":
+      "You appear to be offline. Skipping dependency install and AI setup — run them manually when you're back online.",
+    "scaffold.aiInit": "Configuring ViraStack AI rules...",
+    "scaffold.aiInitDone": "🤖 ViraStack AI agent rules successfully integrated.",
+    "scaffold.aiInitFailed":
+      "Failed to configure ViraStack AI rules.",
+    "scaffold.aiInitSkipped":
+      "Skipping AI setup because dependency install failed.",
+    "scaffold.skillsInitFailed":
+      "Design skills could not be installed. Run manually: npx skills@latest add emilkowalski/skills && npx skills@latest add jakubkrehel/make-interfaces-feel-better",
+
+    "done.title": "You're all set!",
+    "done.partialTitle": "Project files are ready — finish setup manually:",
+    "done.installFailedNote":
+      "Dependency install failed. The project was created, but you need to install packages before running it.",
+    "done.cd": "  cd {dir}",
+    "done.manualInstall": "  {cmd}",
+    "done.manualAi": "  {cmd}",
+    "done.dev": "  {cmd}",
+
+    "add.toolMissing": "Please specify a tool to add. Available tools: {list}.",
+    "add.toolInvalid": 'Unknown tool "{tool}". Available tools: {list}.',
+    "add.notAProject": "No package.json found in the current directory.",
+    "add.installing": "Adding {pkg}...",
+    "add.done": "{pkg} added.",
+    "add.installFailed": "Failed to add {pkg}.",
+
+    help: `Usage:
+  pnpm dlx virastack [init] [name]   Scaffold a new project
+  pnpm dlx virastack add <tool>      Add a ViraStack tool to an existing project
+
+Tools:
+  mask, password, ai
+
+Options:
+  --name <name>         Project name (or pass as positional arg / ".")
+  --template <name>     Template: nextjs | tanstack
+  --tools <list>        Comma-separated tools (e.g. mask,password)
+  --i18n / --no-i18n    Enable or disable the i18n template
+  --yes, -y             Non-interactive mode (use flags/defaults)
+  --skip-install        Scaffold files only; skip install + AI setup
+  --tr                  Ask questions in Turkish
+  --telemetry-disable   Disable anonymous usage tracking
+  -v, --version         Print the version
+  -h, --help            Show this help message
+
+Examples:
+  pnpm dlx virastack
+  pnpm dlx virastack my-app --yes
+  pnpm dlx virastack init my-app --template nextjs --tools mask --yes`,
+  },
+
+  tr: {
+    cancel: "İşlem iptal edildi.",
+    "telemetry.notice":
+      "ViraStack, CLI'ı geliştirmek için anonim kullanım verisi toplar (şablon, i18n tercihi, seçilen araçlar). Hiçbir kişisel veri toplanmaz. --telemetry-disable ile her zaman kapatabilirsiniz.",
+
+    "projectName.message": "Projenizin adı ne olsun?",
+    "projectName.placeholder": "virastack-app",
+    "projectName.errorEmpty":
+      'Lütfen bir proje adı girin, ya da mevcut dizini kullanmak için "." yazın.',
+    "projectName.errorInvalid":
+      "Lütfen geçerli bir npm paket adı girin (küçük harf, rakam, tire).",
+    "projectName.errorNonInteractive":
+      'İnteraktif olmayan modda proje adı zorunlu. Bir ad, --name veya "." verin.',
+    "projectName.confirmNonEmptyDir":
+      '"{dir}" dizini boş değil. Devam edilsin mi?',
+
+    "template.message": "Hangi şablonla başlamak istiyorsunuz?",
+    "template.nextjs.label": "Next.js App Router",
+    "template.nextjs.hint": "Önerilen",
+    "template.tanstack.label": "TanStack Start",
+    "template.tanstack.hint": "Dosya tabanlı routing + SSR",
+    "template.tanstack.notReady":
+      "Bu kurulumda TanStack Start şablonu yok. Next.js kullanılacak.",
+    "template.errorInvalid":
+      'Bilinmeyen şablon "{template}". Kullanılabilir şablonlar: nextjs, tanstack.',
+
+    "i18n.message": "Çoklu dil (i18n) desteği ister misiniz?",
+    "i18n.active": "Evet",
+    "i18n.inactive": "Hayır",
+    "i18n.notReady":
+      "Bu şablon için çoklu dil (i18n) sürümü henüz hazır değil. Standart şablon kullanılacak.",
+
+    "tools.message": "Projenize hangi ViraStack araçları eklensin?",
+    "tools.mask.label": "@virastack/mask",
+    "tools.mask.hint": "Headless input formatlayıcı",
+    "tools.password.label": "@virastack/password",
+    "tools.password.hint": "Şifre görünürlük anahtarı",
+    "tools.ai.label": "@virastack/ai",
+    "tools.ai.hint": "Cursor & Claude için AI kuralları",
+
+    "scaffold.copying": "Proje dosyaları oluşturuluyor...",
+    "scaffold.copyDone": "Proje dosyaları oluşturuldu.",
+    "scaffold.gitInit": "Git deposu başlatılıyor...",
+    "scaffold.gitInitDone": "Git deposu başlatıldı.",
+    "scaffold.gitInitSkipped": "Git başlatma adımı atlandı.",
+    "scaffold.installing": "Bağımlılıklar {pm} ile kuruluyor...",
+    "scaffold.installDone": "Bağımlılıklar kuruldu.",
+    "scaffold.installFailed":
+      "Bağımlılıklar kurulamadı.",
+    "scaffold.skipInstall":
+      "Bağımlılık kurulumu atlanıyor (--skip-install).",
+    "scaffold.offline":
+      "İnternet bağlantısı yok gibi görünüyor. Bağımlılık kurulumu ve AI yapılandırması atlandı — çevrimiçi olduğunuzda manuel çalıştırın.",
+    "scaffold.aiInit": "ViraStack AI kuralları yapılandırılıyor...",
+    "scaffold.aiInitDone": "🤖 ViraStack AI ajan kuralları projeye başarıyla entegre edildi.",
+    "scaffold.aiInitFailed":
+      "ViraStack AI kuralları yapılandırılamadı.",
+    "scaffold.aiInitSkipped":
+      "Bağımlılık kurulumu başarısız olduğu için AI yapılandırması atlandı.",
+    "scaffold.skillsInitFailed":
+      "Tasarım skill'leri kurulamadı. Manuel çalıştırın: npx skills@latest add emilkowalski/skills && npx skills@latest add jakubkrehel/make-interfaces-feel-better",
+
+    "done.title": "Her şey hazır!",
+    "done.partialTitle": "Proje dosyaları hazır — kurulumu manuel tamamlayın:",
+    "done.installFailedNote":
+      "Bağımlılık kurulumu başarısız. Proje oluşturuldu, ancak çalıştırmadan önce paketleri kurmanız gerekiyor.",
+    "done.cd": "  cd {dir}",
+    "done.manualInstall": "  {cmd}",
+    "done.manualAi": "  {cmd}",
+    "done.dev": "  {cmd}",
+
+    "add.toolMissing":
+      "Lütfen eklemek istediğiniz aracı belirtin. Kullanılabilir araçlar: {list}.",
+    "add.toolInvalid": '"{tool}" bilinmeyen bir araç. Kullanılabilir araçlar: {list}.',
+    "add.notAProject": "Bu dizinde package.json bulunamadı.",
+    "add.installing": "{pkg} ekleniyor...",
+    "add.done": "{pkg} eklendi.",
+    "add.installFailed": "{pkg} eklenemedi.",
+
+    help: `Kullanım:
+  pnpm dlx virastack [init] [ad]     Yeni bir proje oluştur
+  pnpm dlx virastack add <araç>      Mevcut projeye bir ViraStack aracı ekle
+
+Araçlar:
+  mask, password, ai
+
+Seçenekler:
+  --name <ad>           Proje adı (veya positional arg / ".")
+  --template <ad>       Şablon: nextjs | tanstack
+  --tools <liste>       Virgülle ayrılmış araçlar (örn. mask,password)
+  --i18n / --no-i18n    i18n şablonunu aç / kapat
+  --yes, -y             İnteraktif olmayan mod (flag/varsayılanlar)
+  --skip-install        Sadece dosyaları oluştur; kurulum + AI atla
+  --tr                  Soruları Türkçe sor
+  --telemetry-disable   Anonim kullanım verisi toplamayı kapat
+  -v, --version         Sürümü göster
+  -h, --help            Bu yardım mesajını göster
+
+Örnekler:
+  pnpm dlx virastack
+  pnpm dlx virastack my-app --yes
+  pnpm dlx virastack init my-app --template nextjs --tools mask --yes`,
+  },
+};
+
+let currentLocale = "en";
+
+export function setLocale(locale) {
+  currentLocale = dictionaries[locale] ? locale : "en";
+}
+
+export function getLocale() {
+  return currentLocale;
+}
+
+export function t(key, vars = {}) {
+  const dictionary = dictionaries[currentLocale] ?? dictionaries.en;
+  const template = dictionary[key] ?? dictionaries.en[key] ?? key;
+  return template.replace(/\{(\w+)\}/g, (_, name) =>
+    name in vars ? String(vars[name]) : `{${name}}`,
+  );
+}

package/src/index.js

@@ -0,0 +1,64 @@
+import { getFlag, hasFlag, parseArgs } from "./utils/args.js";
+import { getCliVersion } from "./utils/package-info.js";
+import { disableTelemetry } from "./utils/telemetry.js";
+import { setLocale, t } from "./i18n.js";
+import { runInit } from "./commands/init.js";
+import { runAdd } from "./commands/add.js";
+import { parseToolsFlag } from "./utils/tools.js";
+
+function resolveI18nFlag(flags) {
+  if (hasFlag(flags, "no-i18n")) return false;
+  if (hasFlag(flags, "i18n")) return true;
+  return undefined;
+}
+
+function buildInitOptions(flags, projectName) {
+  const nameFlag = getFlag(flags, "name");
+  const template = getFlag(flags, "template");
+  const tools = getFlag(flags, "tools");
+
+  return {
+    name: projectName ?? (typeof nameFlag === "string" ? nameFlag : undefined),
+    template: typeof template === "string" ? template : undefined,
+    i18n: resolveI18nFlag(flags),
+    tools: tools === undefined ? undefined : parseToolsFlag(tools),
+    yes: hasFlag(flags, "yes", "y"),
+    skipInstall: hasFlag(flags, "skip-install"),
+  };
+}
+
+export async function main() {
+  const { positionals, flags } = parseArgs(process.argv);
+  setLocale(hasFlag(flags, "tr") ? "tr" : "en");
+
+  if (hasFlag(flags, "telemetry-disable")) {
+    await disableTelemetry();
+  }
+
+  if (hasFlag(flags, "v", "version")) {
+    console.log(getCliVersion());
+    return;
+  }
+
+  if (hasFlag(flags, "h", "help")) {
+    console.log(t("help"));
+    return;
+  }
+
+  const [command, ...rest] = positionals;
+
+  switch (command) {
+    case undefined:
+      await runInit(buildInitOptions(flags));
+      break;
+    case "init":
+      await runInit(buildInitOptions(flags, rest[0]));
+      break;
+    case "add":
+      await runAdd(rest[0]);
+      break;
+    default:
+      // `pnpm dlx virastack my-app --yes` — first token is the project name.
+      await runInit(buildInitOptions(flags, command));
+  }
+}

package/src/utils/args.js

@@ -0,0 +1,60 @@
+/**
+ * Tiny argv parser: splits flags ("--foo", "-f", "--key=value") from
+ * positional args. Kept dependency-free since the CLI surface is small.
+ *
+ * Value-taking long flags consume the next token when it is not itself a flag.
+ */
+
+const VALUE_FLAGS = new Set(["name", "template", "tools"]);
+
+/**
+ * @param {string[]} argv
+ * @returns {{ positionals: string[], flags: Map<string, string | true> }}
+ */
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = new Map();
+  const positionals = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg.startsWith("--") && arg.length > 2) {
+      const body = arg.slice(2);
+      const eq = body.indexOf("=");
+
+      if (eq !== -1) {
+        flags.set(body.slice(0, eq), body.slice(eq + 1));
+        continue;
+      }
+
+      if (VALUE_FLAGS.has(body) && i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        flags.set(body, args[i + 1]);
+        i += 1;
+        continue;
+      }
+
+      flags.set(body, true);
+      continue;
+    }
+
+    if (arg.startsWith("-") && arg.length > 1) {
+      for (const ch of arg.slice(1)) {
+        flags.set(ch, true);
+      }
+      continue;
+    }
+
+    positionals.push(arg);
+  }
+
+  return { positionals, flags };
+}
+
+export function hasFlag(flags, ...names) {
+  return names.some((name) => flags.has(name));
+}
+
+export function getFlag(flags, name) {
+  return flags.get(name);
+}

package/src/utils/copy-template.js

@@ -0,0 +1,80 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+// Lockfiles are excluded on purpose: we run a fresh install with whichever
+// package manager the user invoked the CLI with, and a stale lockfile from
+// the template (always pnpm) would otherwise conflict with npm/yarn/bun.
+const IGNORED_ENTRIES = new Set([
+  ".git",
+  "node_modules",
+  ".next",
+  ".tanstack",
+  ".output",
+  ".nitro",
+  ".wrangler",
+  ".vinxi",
+  "out",
+  "dist",
+  "build",
+  "coverage",
+  ".vercel",
+  ".turbo",
+  ".eslintcache",
+  ".knip",
+  ".DS_Store",
+  "Thumbs.db",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb",
+  "skills-lock.json",
+  ".gitkeep",
+  "assets",
+]);
+
+export function shouldIgnore(name) {
+  if (IGNORED_ENTRIES.has(name)) return true;
+  // Keep .env.example; skip local/secret env files and editor dumps.
+  if (name.startsWith(".env") && name !== ".env.example") return true;
+  if (name.endsWith(".tsbuildinfo")) return true;
+  if (name.endsWith(".log")) return true;
+  return false;
+}
+
+export async function copyTemplate(srcDir, destDir) {
+  await fs.mkdir(destDir, { recursive: true });
+  const entries = await fs.readdir(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (shouldIgnore(entry.name)) continue;
+
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyTemplate(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+export async function dirHasFiles(dir) {
+  try {
+    const entries = await fs.readdir(dir);
+    return entries.some((entry) => entry !== ".gitkeep");
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirEmpty(dir) {
+  try {
+    const entries = await fs.readdir(dir);
+    return entries.length === 0;
+  } catch {
+    // Directory doesn't exist yet — treat as empty, we'll create it.
+    return true;
+  }
+}

package/src/utils/exec.js

@@ -0,0 +1,29 @@
+import spawn from "cross-spawn";
+
+/**
+ * Runs a command and resolves once it exits successfully, rejecting otherwise.
+ * Uses cross-spawn so package manager shims (npm.cmd, pnpm.cmd, ...) resolve on Windows too.
+ */
+export function runCommand(command, args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "ignore", ...options });
+
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`"${command} ${args.join(" ")}" exited with code ${code}`));
+      }
+    });
+  });
+}
+
+export async function commandExists(command) {
+  try {
+    await runCommand(command, ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/git.js

@@ -0,0 +1,38 @@
+import { runCommand, commandExists } from "./exec.js";
+
+export async function isInsideGitRepo(dir) {
+  try {
+    await runCommand("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Best-effort git init + initial commit. Never throws: a missing git binary
+ * or an already-initialized repo (e.g. scaffolding into a monorepo) should
+ * not fail the whole scaffold. Returns whether a new repo was created.
+ */
+export async function initGitRepo(dir) {
+  if (!(await commandExists("git"))) return false;
+  if (await isInsideGitRepo(dir)) return false;
+
+  try {
+    await runCommand("git", ["init"], { cwd: dir });
+    await runCommand("git", ["add", "-A"], { cwd: dir });
+    await runCommand("git", ["commit", "-m", "chore: initial commit from virastack"], {
+      cwd: dir,
+      env: {
+        ...process.env,
+        GIT_AUTHOR_NAME: "ViraStack Start",
+        GIT_AUTHOR_EMAIL: "noreply@virastack.com",
+        GIT_COMMITTER_NAME: "ViraStack Start",
+        GIT_COMMITTER_EMAIL: "noreply@virastack.com",
+      },
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/is-online.js

@@ -0,0 +1,14 @@
+import dns from "node:dns/promises";
+
+/**
+ * Best-effort connectivity check against the npm registry host.
+ * Used to skip install / network-dependent steps when offline.
+ */
+export async function isOnline() {
+  try {
+    await dns.lookup("registry.npmjs.org");
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/package-info.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(path.join(__dirname, "../../package.json"), "utf8"),
+);
+
+export function getCliVersion() {
+  return pkg.version;
+}

package/src/utils/package-manager.js

@@ -0,0 +1,33 @@
+/**
+ * Detects the package manager the CLI was invoked with, mirroring the
+ * technique used by create-next-app and create-vite (npm_config_user_agent).
+ * We never ask the user for this — it keeps the interactive flow short.
+ */
+export function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+
+  if (userAgent.startsWith("pnpm")) return "pnpm";
+  if (userAgent.startsWith("yarn")) return "yarn";
+  if (userAgent.startsWith("bun")) return "bun";
+  return "npm";
+}
+
+export function getInstallArgs(pm) {
+  return pm === "npm" ? ["install", "--legacy-peer-deps"] : ["install"];
+}
+
+export function getAddArgs(pm, packages) {
+  return pm === "npm" ? ["install", "--legacy-peer-deps", ...packages] : ["add", ...packages];
+}
+
+export function getInstallCommand(pm) {
+  return pm === "npm" ? "npm install" : `${pm} install`;
+}
+
+export function getRunDevCommand(pm) {
+  return pm === "npm" ? "npm run dev" : `${pm} dev`;
+}
+
+export function getAiInitCommand() {
+  return "npx --yes @virastack/ai init --force";
+}

package/src/utils/setup-env.js

@@ -0,0 +1,25 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * Seeds a working .env.local from .env.example so `npm run dev` works
+ * immediately after scaffold. Skips if .env.local already exists.
+ */
+export async function setupEnvFile(targetDir) {
+  const examplePath = path.join(targetDir, ".env.example");
+  const localPath = path.join(targetDir, ".env.local");
+
+  try {
+    await fs.access(examplePath);
+  } catch {
+    return false;
+  }
+
+  try {
+    await fs.access(localPath);
+    return false;
+  } catch {
+    await fs.copyFile(examplePath, localPath);
+    return true;
+  }
+}

package/src/utils/telemetry.js

@@ -0,0 +1,86 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getCliVersion } from "./package-info.js";
+
+const CONFIG_DIR = path.join(os.homedir(), ".virastack");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+const DEFAULT_ENDPOINT = "https://virastack.com/api/telemetry";
+const REQUEST_TIMEOUT_MS = 2000;
+
+async function readConfig() {
+  try {
+    const raw = await fs.readFile(CONFIG_FILE, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+async function writeConfig(patch) {
+  try {
+    const current = await readConfig();
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    await fs.writeFile(
+      CONFIG_FILE,
+      `${JSON.stringify({ ...current, ...patch }, null, 2)}\n`,
+    );
+  } catch {
+    // Non-fatal: telemetry preferences are a nice-to-have, never block the CLI.
+  }
+}
+
+export async function isTelemetryDisabled() {
+  if (process.env.VIRASTACK_TELEMETRY_DISABLED === "1") return true;
+  if (process.env.DO_NOT_TRACK === "1") return true;
+
+  const config = await readConfig();
+  return config.telemetryDisabled === true;
+}
+
+export async function disableTelemetry() {
+  await writeConfig({ telemetryDisabled: true });
+}
+
+export async function hasSeenTelemetryNotice() {
+  const config = await readConfig();
+  return config.telemetryNoticeShown === true;
+}
+
+export async function markTelemetryNoticeShown() {
+  await writeConfig({ telemetryNoticeShown: true });
+}
+
+/**
+ * Fire-and-forget anonymous usage event. Never collects personal data
+ * (no project name, no file paths, no IP is read or stored by the CLI) and
+ * never throws — a slow or unreachable endpoint must not affect the CLI flow.
+ */
+export async function trackEvent(event, properties = {}) {
+  if (await isTelemetryDisabled()) return;
+
+  const endpoint = process.env.VIRASTACK_TELEMETRY_URL ?? DEFAULT_ENDPOINT;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  try {
+    await fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        event,
+        properties: {
+          ...properties,
+          cliVersion: getCliVersion(),
+          nodeVersion: process.version,
+          platform: process.platform,
+        },
+      }),
+      signal: controller.signal,
+    });
+  } catch {
+    // Swallow silently — telemetry must never break or slow down the CLI.
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}