alvin-bot 4.4.1

package/bin/cli.js

@@ -0,0 +1,1088 @@
+#!/usr/bin/env node
+
+/**
+ * Alvin Bot CLI — Setup, manage, and chat with your AI agent.
+ *
+ * Usage:
+ *   alvin-bot setup    — Interactive setup wizard
+ *   alvin-bot tui      — Terminal chat UI
+ *   alvin-bot doctor   — Check configuration
+ *   alvin-bot audit    — Security health check
+ *   alvin-bot update   — Pull latest & rebuild
+ *   alvin-bot start    — Start the bot
+ *   alvin-bot stop     — Stop the bot
+ *
+ * Flags:
+ *   --lang en|de       — Language (default: en, auto-detects from LANG env)
+ */
+
+import { createInterface } from "readline";
+import { existsSync, writeFileSync, readFileSync, mkdirSync, copyFileSync, readdirSync } from "fs";
+import { resolve, join } from "path";
+import { homedir } from "os";
+import { execSync } from "child_process";
+import { initI18n, t, getLocale } from "../dist/i18n.js";
+
+// Data directory — same logic as src/paths.ts
+const DATA_DIR = process.env.ALVIN_DATA_DIR || join(homedir(), ".alvin-bot");
+
+// Init i18n early
+initI18n();
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q) => new Promise((r) => rl.question(q, r));
+
+const LOGO = `
+  ╔══════════════════════════════════════╗
+  ║  🤖 Alvin Bot — Setup Wizard v3.0  ║
+  ║  Your Personal AI Agent             ║
+  ╚══════════════════════════════════════╝
+`;
+
+// ── Provider Definitions ────────────────────────────────────────────────────
+
+const PROVIDERS = [
+  {
+    key: "groq",
+    name: "Groq (Llama 3.3 70B)",
+    desc: () => t("provider.groq.desc"),
+    free: true,
+    envKey: "GROQ_API_KEY",
+    signup: "https://console.groq.com",
+    model: "llama-3.3-70b-versatile",
+    needsCLI: false,
+  },
+  {
+    key: "nvidia-kimi-k2.5",
+    name: "NVIDIA NIM (Kimi K2.5 — Best Tool Use)",
+    desc: () => t("provider.nvidia.desc"),
+    free: true,
+    envKey: "NVIDIA_API_KEY",
+    signup: "https://build.nvidia.com",
+    model: "moonshotai/kimi-k2.5",
+    needsCLI: false,
+    fallbackModel: "meta/llama-3.3-70b-instruct",
+  },
+  {
+    key: "gemini-2.5-flash",
+    name: "Google Gemini (2.5 Flash)",
+    desc: () => t("provider.gemini.desc"),
+    free: true,
+    envKey: "GOOGLE_API_KEY",
+    signup: "https://aistudio.google.com",
+    model: "gemini-2.5-flash",
+    needsCLI: false,
+  },
+  {
+    key: "openai",
+    name: "OpenAI (GPT-4o)",
+    desc: () => t("provider.openai.desc"),
+    free: false,
+    envKey: "OPENAI_API_KEY",
+    signup: "https://platform.openai.com",
+    model: "gpt-4o",
+    needsCLI: false,
+  },
+  {
+    key: "openrouter",
+    name: "OpenRouter (100+ Models)",
+    desc: () => t("provider.openrouter.desc"),
+    free: false,
+    envKey: "OPENROUTER_API_KEY",
+    signup: "https://openrouter.ai",
+    model: "anthropic/claude-sonnet-4",
+    needsCLI: false,
+  },
+  {
+    key: "claude-sdk",
+    name: "Claude Agent SDK (Premium)",
+    desc: () => t("provider.claude.desc"),
+    free: false,
+    envKey: null,
+    signup: "https://claude.ai",
+    model: "claude-sonnet-4-20250514",
+    needsCLI: true,
+  },
+];
+
+// ── Provider Validation ────────────────────────────────────────────────────
+
+/**
+ * Validate a provider's API key or auth by making a lightweight API call.
+ * Returns { ok: true, detail: "..." } or { ok: false, error: "..." }.
+ */
+async function validateProviderKey(providerKey, apiKey) {
+  const timeout = 10_000;
+
+  try {
+    switch (providerKey) {
+      case "groq": {
+        const res = await fetch("https://api.groq.com/openai/v1/models", {
+          headers: { Authorization: `Bearer ${apiKey}` },
+          signal: AbortSignal.timeout(timeout),
+        });
+        if (!res.ok) return { ok: false, error: `HTTP ${res.status} — ${res.statusText}` };
+        return { ok: true, detail: "Groq API key valid" };
+      }
+
+      case "nvidia-llama-3.3-70b":
+      case "nvidia-kimi-k2.5": {
+        const res = await fetch("https://integrate.api.nvidia.com/v1/models", {
+          headers: { Authorization: `Bearer ${apiKey}` },
+          signal: AbortSignal.timeout(timeout),
+        });
+        if (!res.ok) return { ok: false, error: `HTTP ${res.status} — ${res.statusText}` };
+        return { ok: true, detail: "NVIDIA API key valid" };
+      }
+
+      case "gemini-2.5-flash": {
+        const res = await fetch(
+          `https://generativelanguage.googleapis.com/v1beta/models?key=${apiKey}`,
+          { signal: AbortSignal.timeout(timeout) }
+        );
+        if (!res.ok) return { ok: false, error: `HTTP ${res.status} — ${res.statusText}` };
+        return { ok: true, detail: "Google API key valid" };
+      }
+
+      case "openai":
+      case "gpt-4o": {
+        const res = await fetch("https://api.openai.com/v1/models", {
+          headers: { Authorization: `Bearer ${apiKey}` },
+          signal: AbortSignal.timeout(timeout),
+        });
+        if (!res.ok) return { ok: false, error: `HTTP ${res.status} — ${res.statusText}` };
+        return { ok: true, detail: "OpenAI API key valid" };
+      }
+
+      case "openrouter": {
+        const res = await fetch("https://openrouter.ai/api/v1/models", {
+          headers: { Authorization: `Bearer ${apiKey}` },
+          signal: AbortSignal.timeout(timeout),
+        });
+        if (!res.ok) return { ok: false, error: `HTTP ${res.status} — ${res.statusText}` };
+        return { ok: true, detail: "OpenRouter API key valid" };
+      }
+
+      case "claude-sdk": {
+        // Find claude binary — check PATH and common locations
+        let claudeBin = null;
+        try {
+          execSync("claude --version", { stdio: "pipe", timeout: 5000 });
+          claudeBin = "claude";
+        } catch {
+          // Not in PATH — try common native install locations
+          const candidates = [
+            join(homedir(), ".local", "bin", "claude"),
+            "/usr/local/bin/claude",
+          ];
+          for (const p of candidates) {
+            if (existsSync(p)) { claudeBin = p; break; }
+          }
+        }
+        if (!claudeBin) {
+          return { ok: false, error: "Claude CLI not installed" };
+        }
+        try {
+          // Use `auth status` instead of `-p "ping"` — faster and doesn't require a full query
+          const authJson = execSync(`${claudeBin} auth status`, {
+            stdio: "pipe", timeout: 10000, encoding: "utf-8",
+          });
+          const authData = JSON.parse(authJson);
+          if (authData.loggedIn) {
+            return { ok: true, detail: `Claude SDK authenticated (${authData.authMethod || "OK"})` };
+          }
+          return { ok: false, error: "Claude CLI not authenticated. Run: claude auth login" };
+        } catch (err) {
+          const msg = err.stdout?.toString() || err.stderr?.toString() || err.message || "";
+          // Try parsing JSON from stdout (auth status exits with code 1 when not logged in)
+          try {
+            const authData = JSON.parse(msg);
+            if (authData.loggedIn) {
+              return { ok: true, detail: `Claude SDK authenticated (${authData.authMethod || "OK"})` };
+            }
+          } catch {}
+          return { ok: false, error: "Claude CLI not authenticated. Run: claude auth login" };
+        }
+      }
+
+      default:
+        return { ok: true, detail: "No validation available for this provider" };
+    }
+  } catch (err) {
+    if (err.name === "TimeoutError" || err.code === "ABORT_ERR") {
+      return { ok: false, error: "Connection timed out — check your internet" };
+    }
+    return { ok: false, error: err.message || "Unknown error" };
+  }
+}
+
+/**
+ * Validate a Telegram bot token by calling getMe.
+ * Returns { ok: true, botName: "@username" } or { ok: false, error: "reason" }.
+ */
+async function validateTelegramToken(token) {
+  if (!token) return { ok: false, error: "No token provided" };
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${token}/getMe`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    const data = await res.json();
+    if (data.ok) {
+      return { ok: true, botName: `@${data.result.username}` };
+    }
+    return { ok: false, error: data.description || "Invalid token" };
+  } catch (err) {
+    return { ok: false, error: err.message || "Connection failed" };
+  }
+}
+
+/**
+ * Run post-setup validation: provider, Telegram, port.
+ */
+async function runPostSetupValidation(providerKey, apiKey, botToken, webPort) {
+  console.log(`\n━━━ Validating Setup ━━━\n`);
+  let allGood = true;
+
+  // 1. Provider
+  if (providerKey === "claude-sdk" || apiKey) {
+    console.log(`  Testing provider...`);
+    const pResult = await validateProviderKey(providerKey, apiKey);
+    if (pResult.ok) {
+      console.log(`  ✅ Provider — ${pResult.detail}`);
+    } else {
+      console.log(`  ❌ Provider — ${pResult.error}`);
+      allGood = false;
+    }
+  } else {
+    console.log(`  ⚠️  Provider: No API key configured`);
+    allGood = false;
+  }
+
+  // 2. Telegram
+  if (botToken) {
+    console.log(`  Testing Telegram...`);
+    const tResult = await validateTelegramToken(botToken);
+    if (tResult.ok) {
+      console.log(`  ✅ Telegram: ${tResult.botName}`);
+    } else {
+      console.log(`  ❌ Telegram: ${tResult.error}`);
+      allGood = false;
+    }
+  } else {
+    console.log(`  ℹ️  Telegram: Skipped (no token)`);
+  }
+
+  // 3. Web UI port
+  const port = webPort || 3100;
+  try {
+    const net = await import("net");
+    await new Promise((resolve, reject) => {
+      const srv = net.createServer();
+      srv.once("error", () => { srv.close(); reject(); });
+      srv.once("listening", () => { srv.close(); resolve(); });
+      srv.listen(port);
+    });
+    console.log(`  ✅ Web UI: Port ${port} available`);
+  } catch {
+    console.log(`  ⚠️  Web UI: Port ${port} in use (another instance running?)`);
+  }
+
+  console.log("");
+
+  if (!allGood) {
+    console.log(`  Some checks failed. Run 'alvin-bot doctor' after fixing to verify.\n`);
+  } else {
+    console.log(`  All checks passed! ✅\n`);
+  }
+
+  return allGood;
+}
+
+// ── Setup Wizard ────────────────────────────────────────────────────────────
+
+async function setup() {
+  console.log(LOGO);
+
+  // ── Prerequisites
+  console.log(t("setup.checkingPrereqs"));
+
+  let hasNode = false;
+  try {
+    const nodeVersion = execSync("node --version", { encoding: "utf-8" }).trim();
+    const major = parseInt(nodeVersion.slice(1));
+    hasNode = major >= 18;
+    console.log(`  ${hasNode ? "✅" : "❌"} Node.js ${nodeVersion}${major < 18 ? ` (${t("setup.needVersion")})` : ""}`);
+  } catch {
+    console.log(`  ❌ ${t("setup.nodeNotFound")}`);
+  }
+
+  if (!hasNode) {
+    console.log(`\n❌ ${t("setup.nodeRequired")}`);
+    rl.close();
+    return;
+  }
+
+  // ── Step 1: Telegram Bot
+  console.log(`\n━━━ ${t("setup.step1")} ━━━`);
+  console.log(t("setup.step1.intro"));
+  console.log(`  (Press Enter to skip — WebUI-only mode)\n`);
+  let botToken = (await ask(t("setup.botToken"))).trim();
+
+  if (!botToken) {
+    console.log(`  ℹ️  Skipping Telegram — bot will run in WebUI-only mode.`);
+    console.log(`  You can add BOT_TOKEN to ~/.alvin-bot/.env later.\n`);
+  } else if (!/^\d+:[A-Za-z0-9_-]+$/.test(botToken)) {
+    console.log(`\n  ⚠️  That doesn't look like a valid bot token.`);
+    console.log(`  Expected format: 123456789:ABCdefGHI-jklMNO`);
+    console.log(`  Get one from @BotFather on Telegram.\n`);
+    const proceed = (await ask(`  Continue anyway? (y/n): `)).trim().toLowerCase();
+    if (proceed !== "y" && proceed !== "yes" && proceed !== "j" && proceed !== "ja") {
+      rl.close();
+      return;
+    }
+  }
+
+  // Validate token with Telegram API
+  if (botToken && /^\d+:[A-Za-z0-9_-]+$/.test(botToken)) {
+    console.log(`  Validating...`);
+    const tgResult = await validateTelegramToken(botToken);
+    if (tgResult.ok) {
+      console.log(`  ✅ Bot: ${tgResult.botName}\n`);
+    } else {
+      console.log(`  ❌ ${tgResult.error}`);
+      console.log(`  Check your token at @BotFather on Telegram.\n`);
+      const retryToken = (await ask(`  Re-enter token (or Enter to skip): `)).trim();
+      if (retryToken) {
+        botToken = retryToken;
+        const retry = await validateTelegramToken(botToken);
+        if (retry.ok) console.log(`  ✅ Bot: ${retry.botName}\n`);
+        else console.log(`  ⚠️  Still invalid — continuing anyway.\n`);
+      }
+    }
+  }
+
+  // ── Step 2: User ID
+  let userId = "";
+  if (botToken) {
+    console.log(`\n━━━ ${t("setup.step2")} ━━━`);
+    console.log(t("setup.step2.intro"));
+    console.log(`  💡 Send /start to @userinfobot on Telegram to find your ID.`);
+    console.log(`  (Press Enter to skip — you can add it later)\n`);
+    userId = (await ask(t("setup.userId"))).trim();
+
+    if (!userId) {
+      console.log(`  ℹ️  Skipping — add ALLOWED_USERS to ~/.alvin-bot/.env later.\n`);
+    } else {
+      // Validate user ID is numeric
+      const userIds = userId.split(",").map(s => s.trim());
+      const invalidIds = userIds.filter(id => !/^\d+$/.test(id));
+      if (invalidIds.length > 0) {
+        console.log(`\n  ⚠️  User IDs must be numbers, got: ${invalidIds.join(", ")}`);
+        console.log(`  Send /start to @userinfobot on Telegram to get your numeric ID.\n`);
+        const proceed = (await ask(`  Continue anyway? (y/n): `)).trim().toLowerCase();
+        if (proceed !== "y" && proceed !== "yes" && proceed !== "j" && proceed !== "ja") {
+          rl.close();
+          return;
+        }
+      }
+
+      // Warn if user ID matches bot token prefix (common mistake)
+      const botIdPrefix = botToken.split(":")[0];
+      const userIdList = userId.split(",").map(s => s.trim());
+      if (userIdList.includes(botIdPrefix)) {
+        console.log(`\n  ⚠️  "${botIdPrefix}" looks like the bot's own ID, not yours!`);
+        console.log(`  The bot token starts with the bot's ID. You need YOUR user ID.`);
+        console.log(`  Send /start to @userinfobot on Telegram to get your ID.\n`);
+        const proceed = (await ask(`  Continue anyway? (y/n): `)).trim().toLowerCase();
+        if (proceed !== "y" && proceed !== "yes" && proceed !== "j" && proceed !== "ja") {
+          userId = "";
+          console.log(`  ℹ️  Cleared — add ALLOWED_USERS to ~/.alvin-bot/.env later.\n`);
+        }
+      }
+    }
+  }
+
+  // ── Step 3: AI Provider
+  console.log(`\n━━━ ${t("setup.step3")} ━━━`);
+  console.log(t("setup.step3.intro") + "\n");
+
+  for (let i = 0; i < PROVIDERS.length; i++) {
+    const p = PROVIDERS[i];
+    const badge = p.free ? "🆓" : "💰";
+    const premium = p.needsCLI ? " ⭐" : "";
+    console.log(`  ${i + 1}. ${badge} ${p.name}${premium}`);
+    console.log(`     ${p.desc()}`);
+    if (p.signup) console.log(`     → ${p.signup}`);
+    console.log("");
+  }
+
+  const providerChoice = parseInt((await ask(t("setup.yourChoice"))).trim()) || 1;
+  let provider = PROVIDERS[Math.max(0, Math.min(providerChoice - 1, PROVIDERS.length - 1))];
+
+  console.log(`\n✅ ${t("setup.providerSelected")} ${provider.name}`);
+
+  // ── Validate Provider ────────────────────────────────────────────
+
+  // Claude SDK: show requirements upfront
+  if (provider.needsCLI) {
+    console.log(`\n  ⚠️  Claude SDK requires one of:`);
+    console.log(`     • Claude Max/Team subscription ($20+/mo)`);
+    console.log(`     • Anthropic API key with Agent SDK access\n`);
+
+    const yesChars = getLocale() === "de" ? ["j", "ja", "y", "yes", ""] : ["y", "yes", ""];
+    const proceed = (await ask(`  Continue with Claude SDK? (Y/n): `)).trim().toLowerCase();
+    if (!yesChars.includes(proceed)) {
+      console.log(`\n  Switching to provider selection...\n`);
+      provider = PROVIDERS[0];
+      console.log(`  ✅ Switched to ${provider.name} (free)\n`);
+    } else {
+      // Check CLI installed
+      let cliInstalled = false;
+      try {
+        execSync("claude --version", { encoding: "utf-8", stdio: "pipe" });
+        cliInstalled = true;
+        console.log(`  ✅ Claude CLI found`);
+      } catch {
+        console.log(`  ⚠️  Claude CLI not found (native binary required).`);
+        console.log(`\n  The Claude Agent SDK needs the native Claude Code binary.`);
+        console.log(`  Install it with:\n`);
+        console.log(`    curl -fsSL https://claude.ai/install.sh | sh\n`);
+        console.log(`  (npm install @anthropic-ai/claude-code does NOT work for this)\n`);
+        const yc = getLocale() === "de" ? ["j", "ja"] : ["y", "yes"];
+        const doInstall = (await ask(`  Already installed or want to try now? (y/n): `)).trim().toLowerCase();
+        if (yc.includes(doInstall)) {
+          console.log(`\n  Installing Claude CLI (native)...`);
+          try {
+            execSync("curl -fsSL https://claude.ai/install.sh | sh", { stdio: "inherit", timeout: 120_000 });
+            // Add ~/.local/bin to PATH for this process (installer puts claude there)
+            const localBin = join(homedir(), ".local", "bin");
+            if (!process.env.PATH.includes(localBin)) {
+              process.env.PATH = `${localBin}:${process.env.PATH}`;
+            }
+            cliInstalled = true;
+            console.log(`  ✅ Claude CLI installed\n`);
+          } catch {
+            console.log(`  ❌ Installation failed. Try manually: curl -fsSL https://claude.ai/install.sh | sh`);
+          }
+        }
+      }
+
+      if (cliInstalled) {
+        console.log(`\n  Checking Claude SDK authentication...`);
+        const authResult = await validateProviderKey("claude-sdk", null);
+        if (!authResult.ok) {
+          console.log(`  ⚠️  ${authResult.error}`);
+          console.log(`\n  Logging in to Claude...`);
+          console.log(`  This will open your browser for authentication.\n`);
+          try {
+            // Find claude binary for auth login
+            let authBin = "claude";
+            const authLocalBin = join(homedir(), ".local", "bin", "claude");
+            if (existsSync(authLocalBin)) authBin = `"${authLocalBin}"`;
+            execSync(`${authBin} auth login --claudeai`, {
+              stdio: "inherit",
+              timeout: 120000,
+            });
+          } catch {
+            console.log(`\n  ⚠️  Auto-login failed. Please run manually in another terminal:`);
+            console.log(`     claude auth login\n`);
+            await ask(`  Press Enter when you've logged in...`);
+          }
+
+          const recheck = await validateProviderKey("claude-sdk", null);
+          if (recheck.ok) {
+            console.log(`\n  ✅ Claude SDK authenticated!\n`);
+          } else {
+            console.log(`\n  ❌ Claude SDK still not working: ${recheck.error}`);
+            console.log(`  Switching to a free provider.\n`);
+            provider = PROVIDERS[0];
+            console.log(`  ✅ Switched to ${provider.name} (free)\n`);
+          }
+        } else {
+          console.log(`  ✅ ${authResult.detail}\n`);
+        }
+      } else {
+        console.log(`\n  Claude CLI not available. Switching to a free provider.\n`);
+        provider = PROVIDERS[0];
+        console.log(`  ✅ Switched to ${provider.name} (free)\n`);
+      }
+    }
+  }
+
+  // Get and validate API key
+  let providerApiKey = "";
+  if (provider.envKey) {
+    console.log(`\n  API key for ${provider.name}:`);
+    console.log(`  Get one at: ${provider.signup}\n`);
+    providerApiKey = (await ask(`  ${provider.envKey}: `)).trim();
+
+    if (providerApiKey) {
+      console.log(`\n  Validating...`);
+      let keyResult = await validateProviderKey(provider.key, providerApiKey);
+      if (keyResult.ok) {
+        console.log(`  ✅ ${keyResult.detail}\n`);
+      } else {
+        console.log(`  ❌ ${keyResult.error}\n`);
+        let resolved = false;
+        for (let attempt = 0; attempt < 2 && !resolved; attempt++) {
+          const choice = (await ask(`  1. Enter new key  2. Switch provider  3. Skip\n  Choice: `)).trim();
+          if (choice === "1") {
+            providerApiKey = (await ask(`\n  ${provider.envKey}: `)).trim();
+            if (providerApiKey) {
+              console.log(`  Validating...`);
+              keyResult = await validateProviderKey(provider.key, providerApiKey);
+              if (keyResult.ok) {
+                console.log(`  ✅ ${keyResult.detail}\n`);
+                resolved = true;
+              } else {
+                console.log(`  ❌ ${keyResult.error}\n`);
+              }
+            }
+          } else if (choice === "2") {
+            provider = PROVIDERS[0];
+            console.log(`\n  Switched to ${provider.name} (free)`);
+            console.log(`  Get a free key at: ${provider.signup}\n`);
+            providerApiKey = (await ask(`  ${provider.envKey}: `)).trim();
+            if (providerApiKey) {
+              const gr = await validateProviderKey(provider.key, providerApiKey);
+              if (gr.ok) console.log(`  ✅ ${gr.detail}\n`);
+              else console.log(`  ⚠️  ${gr.error} — continuing anyway\n`);
+            }
+            resolved = true;
+          } else {
+            console.log(`  ⚠️  Skipping — bot won't work until a valid key is configured.\n`);
+            providerApiKey = "";
+            resolved = true;
+          }
+        }
+      }
+    } else {
+      console.log(`\n  ⚠️  No API key provided. Bot won't work until configured.`);
+      console.log(`  Get one at: ${provider.signup}\n`);
+    }
+  }
+
+  // ── Step 4: Fallback & Extras
+  console.log(`\n━━━ ${t("setup.step4")} ━━━\n`);
+
+  let groqKey = "";
+  if (provider.key !== "groq") {
+    console.log(`  ${t("setup.groqFallback")}\n`);
+    groqKey = (await ask(t("setup.groqKeyPrompt"))).trim();
+    if (!groqKey) {
+      console.log(`  ℹ️  ${t("setup.noGroqKey")}\n`);
+    }
+  } else {
+    groqKey = providerApiKey;
+  }
+
+  console.log(`  ${t("setup.extraKeys")}\n`);
+  const extraKeys = {};
+  if (provider.key !== "nvidia-llama-3.3-70b" && provider.key !== "nvidia-kimi-k2.5") {
+    const nk = (await ask(`  ${t("setup.nvidiaKeyPrompt")}`)).trim();
+    if (nk) extraKeys["NVIDIA_API_KEY"] = nk;
+  }
+  if (provider.key !== "gemini-2.5-flash") {
+    const gk = (await ask(`  ${t("setup.googleKeyPrompt")}`)).trim();
+    if (gk) extraKeys["GOOGLE_API_KEY"] = gk;
+  }
+  if (provider.key !== "openai" && provider.key !== "gpt-4o") {
+    const ok = (await ask(`  ${t("setup.openaiKeyPrompt")}`)).trim();
+    if (ok) extraKeys["OPENAI_API_KEY"] = ok;
+  }
+
+  // Fallback order
+  console.log(`\n  ${t("setup.fallbackOrder")}`);
+  const availableFallbacks = [];
+  if (groqKey && provider.key !== "groq") availableFallbacks.push("groq");
+  if (extraKeys["NVIDIA_API_KEY"]) availableFallbacks.push("nvidia-llama-3.3-70b");
+  // If NVIDIA is primary, add llama as fallback automatically
+  if (provider.key === "nvidia-kimi-k2.5" && !availableFallbacks.includes("nvidia-llama-3.3-70b")) {
+    availableFallbacks.push("nvidia-llama-3.3-70b");
+  }
+  if (extraKeys["GOOGLE_API_KEY"]) availableFallbacks.push("gemini-2.5-flash");
+  if (extraKeys["OPENAI_API_KEY"]) availableFallbacks.push("gpt-4o");
+
+  if (availableFallbacks.length > 0) {
+    console.log(`     ${t("setup.defaultOrder")} ${availableFallbacks.join(" → ")}`);
+    const customOrder = (await ask(`     ${t("setup.customOrder")}`)).trim();
+    if (customOrder) {
+      availableFallbacks.length = 0;
+      availableFallbacks.push(...customOrder.split(",").map(s => s.trim()).filter(Boolean));
+    }
+  } else {
+    console.log(`     ${t("setup.noFallbacks")}`);
+  }
+
+  console.log("");
+  const webPassword = (await ask(t("setup.webPassword"))).trim();
+
+  // ── Step 5: Platforms
+  console.log(`\n━━━ ${t("setup.step5")} ━━━`);
+  console.log(`${t("setup.step5.intro")}\n`);
+  console.log(`  1. ${t("setup.platform.telegramOnly")}`);
+  console.log(`  2. ${t("setup.platform.whatsapp")}`);
+  console.log(`  3. ${t("setup.platform.later")}\n`);
+
+  const platformChoice = parseInt((await ask(t("setup.platformChoice"))).trim()) || 1;
+  const enableWhatsApp = platformChoice === 2;
+
+  // ── Write .env
+  console.log(`\n${t("setup.writingConfig")}`);
+
+  const envLines = [
+    "# === Telegram ===",
+    `BOT_TOKEN=${botToken || ""}`,
+    `ALLOWED_USERS=${userId || ""}`,
+    "",
+    "# === AI Provider ===",
+    `PRIMARY_PROVIDER=${provider.key}`,
+  ];
+
+  if (provider.envKey && providerApiKey) {
+    envLines.push(`${provider.envKey}=${providerApiKey}`);
+  }
+
+  if (groqKey && provider.key !== "groq") {
+    envLines.push(`GROQ_API_KEY=${groqKey}`);
+  }
+
+  for (const [envKey, value] of Object.entries(extraKeys)) {
+    envLines.push(`${envKey}=${value}`);
+  }
+
+  if (availableFallbacks.length > 0) {
+    envLines.push(`FALLBACK_PROVIDERS=${availableFallbacks.join(",")}`);
+  }
+
+  envLines.push("");
+  envLines.push("# === Agent ===");
+  envLines.push(`WORKING_DIR=${os.homedir()}`);
+  envLines.push("MAX_BUDGET_USD=5.0");
+
+  if (webPassword) {
+    envLines.push(`WEB_PASSWORD=${webPassword}`);
+  }
+
+  envLines.push("WEB_PORT=3100");
+
+  if (enableWhatsApp) {
+    envLines.push("");
+    envLines.push("# === WhatsApp ===");
+    envLines.push("WHATSAPP_ENABLED=true");
+  }
+
+  const envContent = envLines.join("\n") + "\n";
+
+  // Ensure DATA_DIR exists
+  if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR, { recursive: true });
+  }
+
+  // Write .env to ~/.alvin-bot/.env (works for both global npm install and local dev)
+  const envPath = resolve(DATA_DIR, ".env");
+
+  if (existsSync(envPath)) {
+    const backup = `${envPath}.backup-${Date.now()}`;
+    writeFileSync(backup, readFileSync(envPath));
+    console.log(`  ${t("setup.backup")} ${backup}`);
+  }
+
+  writeFileSync(envPath, envContent);
+  console.log(`  ✅ Config saved to ${envPath}`);
+
+  // Also write to cwd if we're in a dev/git environment (convenience)
+  const cwdEnvPath = resolve(process.cwd(), ".env");
+  const isDevMode = existsSync(resolve(process.cwd(), ".git"));
+  if (isDevMode && cwdEnvPath !== envPath) {
+    writeFileSync(cwdEnvPath, envContent);
+    console.log(`  ✅ Dev copy saved to ${cwdEnvPath}`);
+  }
+
+  // Create ~/.alvin-bot/ data directory
+  const memoryDir = resolve(DATA_DIR, "memory");
+  if (!existsSync(memoryDir)) {
+    mkdirSync(memoryDir, { recursive: true });
+  }
+
+  // Create soul.md if not exists
+  const soulPath = resolve(DATA_DIR, "soul.md");
+  if (!existsSync(soulPath)) {
+    const soulExample = resolve(process.cwd(), "SOUL.example.md");
+    if (existsSync(soulExample)) {
+      copyFileSync(soulExample, soulPath);
+      console.log("  ✅ soul.md initialized from example");
+    } else {
+      writeFileSync(soulPath, t("soul.default"));
+      console.log(`  ✅ ${t("setup.soulCreated")}`);
+    }
+  }
+
+  // Initialize memory/MEMORY.md if not exists
+  const memoryMdPath = resolve(DATA_DIR, "memory", "MEMORY.md");
+  if (!existsSync(memoryMdPath)) {
+    writeFileSync(memoryMdPath, "# Long-term Memory\n\n> This file is your agent's long-term memory. Add important context here.\n> It persists across sessions and is read at every startup.\n");
+    console.log("  ✅ memory/MEMORY.md created");
+  }
+
+  // Initialize custom-models.json if not exists
+  const customModelsPath = resolve(DATA_DIR, "custom-models.json");
+  if (!existsSync(customModelsPath)) {
+    writeFileSync(customModelsPath, "[]");
+    console.log("  ✅ custom-models.json initialized");
+  }
+
+  // Copy TOOLS.example.md → tools.md if not exists
+  const toolsMdPath = resolve(DATA_DIR, "tools.md");
+  const toolsMdExample = resolve(process.cwd(), "TOOLS.example.md");
+  if (!existsSync(toolsMdPath) && existsSync(toolsMdExample)) {
+    copyFileSync(toolsMdExample, toolsMdPath);
+    console.log("  ✅ Custom tools initialized from example (tools.md)");
+  }
+
+  // Copy CLAUDE.example.md → CLAUDE.md in BOT_ROOT if not exists
+  const claudePath = resolve(process.cwd(), "CLAUDE.md");
+  const claudeExample = resolve(process.cwd(), "CLAUDE.example.md");
+  if (!existsSync(claudePath) && existsSync(claudeExample)) {
+    copyFileSync(claudeExample, claudePath);
+    console.log("  ✅ CLAUDE.md initialized from example");
+  }
+
+  // ── Build (only for local/dev installs — global npm installs already have dist/)
+  const isGlobalInstall = !existsSync(resolve(process.cwd(), "tsconfig.json"));
+  if (!isGlobalInstall) {
+    console.log(`\n${t("setup.building")}`);
+    try {
+      execSync("npm run build", { stdio: "inherit" });
+      console.log(`  ✅ ${t("setup.buildOk")}`);
+    } catch {
+      console.log(`\n  ❌ ${t("setup.buildFailed")}`);
+      console.log(`  The bot cannot start without a successful build.`);
+      console.log(`  Try running 'npm run build' manually to see the error.\n`);
+      rl.close();
+      return;
+    }
+  }
+
+  // ── Post-Setup Validation ──────────────────────────────────────────────
+  await runPostSetupValidation(provider.key, providerApiKey, botToken, 3100);
+
+  // ── Summary
+  const providerInfo = "";
+
+  const startCmds = isGlobalInstall
+    ? `  alvin-bot start                  (start the bot)
+  alvin-bot doctor                 (check configuration)
+
+  # Keep running permanently:
+  npm install -g pm2
+  pm2 start "alvin-bot start" --name alvin-bot
+  pm2 save && pm2 startup`
+    : `  npm run dev                       (development, hot reload)
+  npm start                         (production)
+  pm2 start ecosystem.config.cjs    (production, auto-restart)`;
+
+  console.log(`
+━━━ ${t("setup.done")} ━━━
+
+  🤖 Provider: ${provider.name}
+  💬 Telegram: @... (check @BotFather)
+  🌐 Web UI: http://localhost:3100${webPassword ? ` (${t("setup.passwordProtected")})` : ""}
+  📁 Config: ${envPath}
+${enableWhatsApp ? `  📱 ${t("setup.scanQr")}\n` : ""}${providerInfo}
+Start:
+${startCmds}
+
+Bot commands:
+  /help     — Show all commands
+  /model    — Switch AI model
+  /effort   — Set thinking depth
+  /imagine  — Generate images
+  /web      — Web search
+  /cron     — Scheduled tasks
+
+${t("setup.haveFun")}
+`);
+
+  rl.close();
+}
+
+// ── Doctor ──────────────────────────────────────────────────────────────────
+
+async function doctor() {
+  console.log(`\n━━━ Alvin Bot Health Check ━━━\n`);
+
+  // ── System ──
+  console.log("  System:");
+  try {
+    const v = execSync("node --version", { encoding: "utf-8" }).trim();
+    const major = parseInt(v.slice(1));
+    console.log(`  ${major >= 18 ? "✅" : "❌"} Node.js ${v}${major < 18 ? " (need ≥ 18)" : ""}`);
+  } catch {
+    console.log("  ❌ Node.js not found");
+  }
+
+  // Config file
+  const dataEnvPath = resolve(DATA_DIR, ".env");
+  const cwdEnvPath = resolve(process.cwd(), ".env");
+  const envPath = existsSync(dataEnvPath) ? dataEnvPath : existsSync(cwdEnvPath) ? cwdEnvPath : null;
+
+  if (envPath) {
+    console.log(`  ✅ Config: ${envPath}`);
+  } else {
+    console.log(`  ❌ No .env found`);
+    console.log(`     Run: alvin-bot setup\n`);
+    return;
+  }
+
+  const env = readFileSync(envPath, "utf-8");
+  const getEnv = (key) => {
+    const m = env.match(new RegExp(`^${key}=(.+)$`, "m"));
+    return m?.[1]?.trim() || "";
+  };
+
+  // Build
+  const distPaths = [
+    resolve(process.cwd(), "dist/index.js"),
+    resolve(import.meta.dirname || ".", "../dist/index.js"),
+  ];
+  console.log(`  ${distPaths.some(p => existsSync(p)) ? "✅" : "❌"} Build present`);
+
+  // ── Provider ──
+  console.log("\n  Provider:");
+  const primary = getEnv("PRIMARY_PROVIDER");
+  if (primary) {
+    const apiKeyMap = {
+      groq: "GROQ_API_KEY",
+      "nvidia-llama-3.3-70b": "NVIDIA_API_KEY",
+      "nvidia-kimi-k2.5": "NVIDIA_API_KEY",
+      "gemini-2.5-flash": "GOOGLE_API_KEY",
+      openai: "OPENAI_API_KEY",
+      "gpt-4o": "OPENAI_API_KEY",
+      openrouter: "OPENROUTER_API_KEY",
+    };
+    const keyName = apiKeyMap[primary];
+    const key = keyName ? getEnv(keyName) : null;
+
+    console.log(`  Validating ${primary}...`);
+    const result = await validateProviderKey(primary, key);
+    if (result.ok) {
+      console.log(`  ✅ ${primary} — ${result.detail}`);
+    } else {
+      console.log(`  ❌ ${primary} — ${result.error}`);
+    }
+
+    const fallbacks = getEnv("FALLBACK_PROVIDERS");
+    if (fallbacks) {
+      console.log(`  ℹ️  Fallbacks: ${fallbacks}`);
+    } else {
+      console.log(`  ⚠️  No fallback providers configured`);
+    }
+  } else {
+    console.log(`  ❌ PRIMARY_PROVIDER not set`);
+  }
+
+  // ── Telegram ──
+  console.log("\n  Telegram:");
+  const botToken = getEnv("BOT_TOKEN");
+  if (botToken) {
+    const tResult = await validateTelegramToken(botToken);
+    if (tResult.ok) {
+      console.log(`  ✅ Bot: ${tResult.botName}`);
+    } else {
+      console.log(`  ❌ ${tResult.error}`);
+    }
+  } else {
+    console.log(`  ⚠️  BOT_TOKEN not configured (WebUI-only mode)`);
+  }
+
+  const users = getEnv("ALLOWED_USERS");
+  if (users) {
+    const ids = users.split(",").map(s => s.trim());
+    const invalid = ids.filter(id => !/^\d+$/.test(id));
+    if (invalid.length > 0) {
+      console.log(`  ⚠️  ALLOWED_USERS has non-numeric: ${invalid.join(", ")}`);
+    } else {
+      console.log(`  ✅ ALLOWED_USERS: ${ids.length} user${ids.length > 1 ? "s" : ""}`);
+    }
+  } else if (botToken) {
+    console.log(`  ❌ ALLOWED_USERS not set (nobody can message the bot)`);
+  }
+
+  // ── Extras ──
+  console.log("\n  Extras:");
+
+  if (existsSync(resolve(DATA_DIR, "soul.md")) || existsSync(resolve(process.cwd(), "SOUL.md"))) {
+    console.log(`  ✅ Personality (soul.md)`);
+  } else {
+    console.log(`  ⚠️  No soul.md (bot uses default personality)`);
+  }
+
+  const pluginsDir = resolve(process.cwd(), "plugins");
+  if (existsSync(pluginsDir)) {
+    try {
+      const plugins = readdirSync(pluginsDir).filter(d => {
+        try { return existsSync(resolve(pluginsDir, d, "index.js")); } catch { return false; }
+      });
+      if (plugins.length > 0) console.log(`  ✅ Plugins: ${plugins.join(", ")}`);
+    } catch { /* ignore */ }
+  }
+
+  if (env.includes("WHATSAPP_ENABLED=true")) {
+    const chromePaths = [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/usr/bin/google-chrome", "/usr/bin/chromium",
+    ];
+    const hasChrome = chromePaths.some(p => existsSync(p));
+    console.log(`  ${hasChrome ? "✅" : "⚠️ "} WhatsApp (Chrome: ${hasChrome ? "found" : "not found"})`);
+  }
+
+  console.log("");
+}
+
+// ── Update ──────────────────────────────────────────────────────────────────
+
+async function update() {
+  console.log(`${t("update.title")}\n`);
+
+  try {
+    const isGit = existsSync(resolve(process.cwd(), ".git"));
+
+    if (isGit) {
+      console.log(`  ${t("update.pulling")}`);
+      execSync("git pull", { stdio: "inherit" });
+      console.log(`\n  ${t("update.installing")}`);
+      execSync("npm install", { stdio: "inherit" });
+      console.log(`\n  ${t("update.building")}`);
+      execSync("npm run build", { stdio: "inherit" });
+      console.log(`\n  ✅ ${t("update.done")}`);
+    } else {
+      console.log(`  ${t("update.npm")}`);
+      execSync("npm update alvin-bot", { stdio: "inherit" });
+      console.log(`\n  ✅ ${t("update.done")}`);
+    }
+  } catch (err) {
+    console.error(`\n  ❌ ${t("update.failed")} ${err.message}`);
+  }
+}
+
+// ── Version ─────────────────────────────────────────────────────────────────
+
+async function version() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(import.meta.dirname || ".", "../package.json"), "utf-8"));
+    console.log(`Alvin Bot v${pkg.version}`);
+  } catch {
+    console.log("Alvin Bot (version unknown)");
+  }
+}
+
+// ── CLI Router ──────────────────────────────────────────────────────────────
+
+const cmd = process.argv[2];
+switch (cmd) {
+  case "setup":
+    setup().catch(console.error);
+    break;
+  case "doctor":
+    doctor().catch(console.error);
+    break;
+  case "update":
+    update().catch(console.error);
+    break;
+  case "start": {
+    const fg = process.argv.includes("--foreground") || process.argv.includes("-f");
+    if (fg) {
+      import("../dist/index.js");
+    } else {
+      // Start via PM2 (background, survives terminal close, auto-restart on crash)
+      try {
+        execSync("pm2 --version", { stdio: "pipe" });
+      } catch {
+        // PM2 not installed — install it
+        console.log("Installing PM2 for background operation...");
+        try {
+          execSync("npm install -g pm2", { stdio: "inherit", timeout: 60000 });
+        } catch {
+          console.log("Could not install PM2. Starting in foreground instead.");
+          console.log("Tip: Install PM2 manually (npm install -g pm2) to run in background.\n");
+          await import("../dist/index.js");
+          break;
+        }
+      }
+      const cliPath = resolve(join(import.meta.dirname, "cli.js"));
+      try {
+        // Stop existing instance if running
+        execSync("pm2 delete alvin-bot", { stdio: "pipe" });
+      } catch { /* not running — fine */ }
+      execSync(`pm2 start "${cliPath}" --name alvin-bot -- start --foreground`, {
+        stdio: "inherit",
+        timeout: 15000,
+      });
+      console.log("\n✅ Bot is running in the background.");
+      console.log("   Logs:    pm2 logs alvin-bot");
+      console.log("   Stop:    alvin-bot stop");
+      console.log("   Restart: alvin-bot start\n");
+      process.exit(0);
+    }
+    break;
+  }
+  case "stop": {
+    try {
+      execSync("pm2 stop alvin-bot", { stdio: "inherit", timeout: 10000 });
+    } catch {
+      console.log("Bot is not running via PM2. If running in foreground, use Ctrl+C.");
+    }
+    process.exit(0);
+  }
+  case "tui":
+  case "chat":
+    import("../dist/tui/index.js").then(m => m.startTUI()).catch(console.error);
+    break;
+  case "search": {
+    const searchQuery = process.argv.slice(3).join(" ");
+    if (!searchQuery) {
+      console.log("Usage: alvin-bot search <query>");
+      console.log('Example: alvin-bot search "cover letter"');
+      process.exit(1);
+    }
+    const { searchSelf, formatSearchResults } = await import("../dist/services/self-search.js");
+    const results = await searchSelf(searchQuery);
+    console.log(formatSearchResults(results));
+    process.exit(0);
+  }
+  case "audit": {
+    const { runAudit, formatAuditReport } = await import("../dist/services/security-audit.js");
+    const checks = runAudit();
+    console.log(formatAuditReport(checks));
+    process.exit(checks.some(c => c.status === "FAIL") ? 1 : 0);
+    break;
+  }
+  case "version":
+  case "--version":
+  case "-v":
+    version();
+    break;
+  default:
+    console.log(`
+${t("cli.title")}
+
+${t("cli.commands")}
+  setup     ${t("cli.setup")}
+  tui       ${t("cli.tui")}
+  chat      ${t("cli.chatAlias")}
+  doctor    ${t("cli.doctorDesc")}
+  audit     Security health check (permissions, secrets, config)
+  search    Search your assets, memories, and skills
+  update    ${t("cli.updateDesc")}
+  start     ${t("cli.startDesc")} (background via PM2)
+  start -f  Start in foreground (for debugging)
+  stop      Stop the bot
+  version   ${t("cli.versionDesc")}
+
+${t("cli.example")}
+  alvin-bot setup
+  alvin-bot tui
+  alvin-bot tui --lang de
+`);
+}