alvin-bot 4.23.1 → 4.25.0

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.25.0] — 2026-05-13
+
+### Auto-bootstrap media tools (yt-dlp + ffmpeg) on every setup and update
+
+`yt-dlp` and `ffmpeg` are now installed (or upgraded) automatically whenever the user runs `alvin-bot setup` or `alvin-bot update` — silently, one line of status per tool, non-fatal on failure. These are the two foundational media tools used by the transcribe / download / video-generate / voice skills and they break or need patches often enough that "whatever brew shipped last week" is materially worse than "current latest" for ordinary users.
+
+**No bundling. No redistribution.** alvin-bot shells out to the user's own system package manager (Homebrew on macOS, `pipx`/`apt` on Linux). The user remains the licensee under each tool's upstream license. License notes are recorded in `BOOTSTRAP_TOOLS` for transparency:
+
+- **yt-dlp** — Unlicense (public-domain equivalent)
+- **ffmpeg** — LGPL-2.1+ (Brew default build; no GPL-only codecs are pulled in by the default formula)
+
+### Behaviour
+
+| User action | What happens |
+|---|---|
+| `alvin-bot setup` (interactive) | At the very start, before any prompt: tries `brew install yt-dlp` + `brew install ffmpeg` (or `pipx`/`apt` on Linux) if missing, runs `brew upgrade` if already installed. One status line per tool. |
+| `alvin-bot update` | After `npm install -g` / `git pull` completes, the same bootstrap step runs — so an update of the bot also refreshes media tools. |
+| `alvin-bot setup --no-bootstrap-tools` | Skips the bootstrap step entirely. For users who want full manual control. |
+| Failure (no brew, no network, etc.) | Setup/update continues; user sees a `⚠` warning line; bot still works for everything that doesn't need media tools. |
+
+### Implementation detail that matters
+
+On macOS, `brew upgrade <pkg>` does **not** automatically refresh the formula database before checking versions — meaning a user on stale brew (haven't run `brew update` in weeks) would see "already at latest" even when newer versions exist. The bootstrap step runs `brew update --quiet` **once per session** before any brew upgrade, memoized so multiple tools share the refresh cost. Cost: 5-30 s on first invocation, zero on subsequent calls.
+
+### End-to-end verified on a real Apple Silicon Mac
+
+Two scenarios run manually after the code change:
+
+1. **Both tools present, brew formulas stale.** Bootstrap ran `brew update --quiet` + `brew upgrade yt-dlp/ffmpeg`. yt-dlp's brew-listed and upstream latest both confirmed at `2026.03.17` (verified via `brew info yt-dlp` and `yt-dlp -U`'s self-check) — code correctly reported "up-to-date". ffmpeg's pre-existing dylib-link failure (`libx265.215.dylib not found`) was incidentally fixed by `brew upgrade ffmpeg`, which is the exact kind of bit-rot the bootstrap is meant to catch.
+
+2. **yt-dlp deliberately uninstalled, run `alvin-bot update` again.** Bootstrap correctly detected `command -v yt-dlp` → not found, ran `brew install yt-dlp`, reported "installed (2026.03.17)" (note the differentiated wording vs "up-to-date" — same versioning convention as `npm install` vs `npm update`). Post-state: `/opt/homebrew/bin/yt-dlp` back and working.
+
+## [4.24.0] — 2026-05-12
+
+### Switch AI providers cleanly after install — new `alvin-bot provider` command
+
+End-to-end UX gap closed: until now, the only way to change AI provider after the initial install was to re-run the full setup wizard (Telegram, AI provider, tools menu, …) or hand-edit `~/.alvin-bot/.env` without guidance. Both options leak past the user's actual intent — "I just want to change the AI provider, please."
+
+```bash
+alvin-bot provider list                 # show all providers + per-provider install/key status
+alvin-bot provider show                 # detailed info on the current provider
+alvin-bot provider switch <key>         # interactive setup + targeted .env merge
+alvin-bot provider doctor               # validate current provider's auth/key against its API
+```
+
+`<key>` accepts both canonical slugs (`claude-sdk`, `groq`, `gemini-2.5-flash`, …) and short aliases (`claude`, `codex`, `gemini`, `nvidia`, `gpt`, `gemma`).
+
+### Provider-specific guided setup, reused from the setup wizard
+
+The same install-the-CLI / run-OAuth-login / prompt-for-API-key logic that the setup wizard already uses for first-time configuration is now reusable. Refactored into three small primitives:
+
+- **`configureClaudeSdkInline()`** — detects native `claude` binary, offers `curl -fsSL https://claude.ai/install.sh | sh` if missing, runs `claude auth login --claudeai` if not authenticated, re-validates.
+- **`configureCodexCliInline()`** — new. Detects `codex` binary, offers `npm install -g @openai/codex` if missing, runs `codex login` (ChatGPT OAuth) if not authenticated.
+- **`configureApiKeyInline(provider, opts)`** — for groq / nvidia / gemini / openai / openrouter. Tests an existing key in `.env` first, prompts for a new one if invalid, retries once, "save anyway" path for offline first-time setup.
+
+### Safe `.env` merge — never destroys, never duplicates
+
+The new `setEnvKey()` + `commentEnvKey()` helpers do **byte-preserving** in-place updates of `~/.alvin-bot/.env`:
+
+- `PRIMARY_PROVIDER` line is **updated in place**, not appended. No duplicates.
+- The new provider's API key (if any) is set the same way — also handles "previously commented out by an earlier switch" → uncomment + update.
+- The previous provider's API key is **parked, not deleted**: e.g. `# GROQ_API_KEY=...  # parked 2026-05-12: was for groq, kept for rollback`. Rollback by un-commenting; secret never lost.
+- Everything else (`BOT_TOKEN`, `ALLOWED_USERS`, `FALLBACK_PROVIDERS`, `WEB_*`, custom comments, blank lines, custom additions) is preserved byte-for-byte.
+
+### Auto-restart under launchd
+
+After a successful switch, on macOS with `~/Library/LaunchAgents/com.alvinbot.app.plist` present, the command offers to run `launchctl kickstart -k gui/$UID/com.alvinbot.app` to apply the new provider without manual intervention. Default is Yes; press Enter to restart, `n` to defer.
+
+### Robustness: `ask()` no longer crashes on stdin EOF
+
+`readline.question` throws `ERR_USE_AFTER_CLOSE` once stdin emits 'close' (piped input drained, terminal closed). The `ask()` helper now catches this and returns `""` — same semantic as "user pressed Enter on a prompt", so the calling wizard step picks its default. Fixes a class of crashes for users running setup wizards over `expect` / SSH-piped install scripts / CI.
+
+### Manual end-to-end test on a fresh-ish Apple Silicon Mac (.75)
+
+- `provider list` shows all 8 providers with per-provider status (CLI installed, API key present, OAuth-authenticated)
+- `provider show` reports current = `claude-sdk` with model + key var + fallbacks
+- `provider doctor` validates auth/key against the live API
+- `provider switch groq` with a deliberately invalid key: API returns 401, "Save anyway" path is taken, `.env` is mutated correctly: `PRIMARY_PROVIDER=groq`, `GROQ_API_KEY=…` set, all other vars + comments preserved byte-for-byte
+- `provider switch claude-sdk` (rollback): existing claude binary detected, auth-status warning surfaced, login prompt declined, `.env` mutated: `PRIMARY_PROVIDER=claude-sdk` back, `GROQ_API_KEY` line **commented and stamped** `# GROQ_API_KEY=...  # parked 2026-05-12: was for groq, kept for rollback`, every other line untouched
+
 ## [4.23.1] — 2026-05-12
 
 ### Fixed: install.sh now installs via npm (no more git clone collision)

package/bin/cli.js

@@ -42,7 +42,21 @@ const ensureRL = () => {
   return rl;
 };
 const closeRL = () => { if (rl) { rl.close(); rl = null; } };
-const ask = (q) => new Promise((r) => ensureRL().question(q, r));
+// Robust ask(): if stdin has already closed (piped input EOF, or a previous
+// ask completed and the interface emitted 'close'), `rl.question` throws
+// ERR_USE_AFTER_CLOSE. Treat that as empty input rather than crashing the
+// wizard — the caller can decide whether empty means "default" or "skip".
+const ask = (q) => new Promise((resolve, reject) => {
+  try {
+    ensureRL().question(q, resolve);
+  } catch (err) {
+    if (err && err.code === "ERR_USE_AFTER_CLOSE") {
+      resolve("");
+    } else {
+      reject(err);
+    }
+  }
+});
 
 const LOGO = `
   ╔══════════════════════════════════════╗
@@ -221,6 +235,165 @@ function hasCommand(name) {
   }
 }
 
+// ─── Auto-bootstrap media tools ───────────────────────────────────────────
+//
+// These two are universally useful for the media-related skills (transcribe,
+// download, video-generate, voice) and they break or need patches often enough
+// (yt-dlp especially — YouTube changes its extractors weekly) that "always
+// latest" is materially better than "whatever brew shipped last week".
+//
+// The installer here is NOT redistribution: we shell out to the user's own
+// system package manager (brew/apt) to install or upgrade. The user remains
+// the licensee under the tool's upstream license. License notes per tool are
+// in BOOTSTRAP_TOOLS for transparency — and `--no-bootstrap-tools` lets users
+// opt out entirely.
+//
+// Output is intentionally quiet: a single status line per tool, install output
+// only surfaces on failure. Setup-flow is never blocked by a bootstrap-tool
+// failure — the user gets a warning, the wizard continues.
+
+const BOOTSTRAP_TOOLS = [
+  {
+    cmd: "yt-dlp",
+    name: "yt-dlp",
+    license: "Unlicense (public domain equivalent)",
+    install: { macos: "brew install yt-dlp", linux: "pipx install yt-dlp" },
+    // yt-dlp ships its own `-U` self-updater but it bails out for binaries
+    // installed via brew (can't write to /opt/homebrew/). Always go through
+    // the package manager that originally installed it.
+    upgrade: { macos: "brew upgrade yt-dlp", linux: "pipx upgrade yt-dlp" },
+    // Linux fallback if pipx isn't available
+    linuxSkipIf: "pipx",
+  },
+  {
+    cmd: "ffmpeg",
+    name: "ffmpeg",
+    license: "LGPL-2.1+ (brew default; auto-install via your package manager — you remain the licensee)",
+    install: { macos: "brew install ffmpeg", linux: "sudo apt-get install -y ffmpeg" },
+    upgrade: { macos: "brew upgrade ffmpeg", linux: "sudo apt-get install --only-upgrade -y ffmpeg" },
+  },
+];
+
+// Memoized: `brew update` is slow (5-30s) but needs to run at least once
+// per session before `brew upgrade` so we get the latest formula info,
+// not whatever was cached locally weeks ago. Without this we hit the
+// "brew thinks yt-dlp is at 2026-03-17 because formula DB is stale" trap.
+let brewFormulasRefreshed = false;
+function refreshBrewFormulas() {
+  if (brewFormulasRefreshed) return;
+  if (!hasCommand("brew")) return;
+  try {
+    execSync("brew update --quiet", { stdio: "pipe", timeout: 90_000 });
+  } catch {
+    // brew update can fail transiently (rate limits, network). Non-fatal:
+    // we'll fall through with whatever cached formulas brew has.
+  }
+  brewFormulasRefreshed = true;
+}
+
+/**
+ * Detect the major package manager available for non-interactive installs.
+ * Returns "macos" (homebrew), "linux" (apt-based), or null.
+ */
+function detectPlatformPm() {
+  if (process.platform === "darwin") return "macos";
+  if (process.platform === "linux") return "linux";
+  return null;
+}
+
+/**
+ * Quietly install or upgrade a single bootstrap tool. Returns a brief status
+ * string for the caller to print. Never throws — failures are reported as
+ * { ok: false, message } so the calling step keeps going.
+ */
+function bootstrapOneTool(tool, platform) {
+  const cmdAvailable = hasCommand(tool.cmd);
+
+  // Linux-only prerequisite check (e.g. pipx for yt-dlp).
+  if (platform === "linux" && tool.linuxSkipIf && !hasCommand(tool.linuxSkipIf)) {
+    return { ok: false, message: `${tool.name} skipped — needs '${tool.linuxSkipIf}' on Linux` };
+  }
+
+  // Decide whether the install/upgrade command goes through brew on macOS.
+  // If so, refresh the formula DB once before any upgrade attempts so we
+  // don't end up running `brew upgrade` against weeks-old formula info.
+  const installCmd = tool.install[platform];
+  const upgradeCmd = tool.upgrade && tool.upgrade[platform];
+  if (platform === "macos" && (String(installCmd).startsWith("brew") || String(upgradeCmd).startsWith("brew"))) {
+    refreshBrewFormulas();
+  }
+
+  // ── Upgrade path: tool is already installed ────────────────────────────
+  if (cmdAvailable) {
+    if (!upgradeCmd) {
+      return { ok: true, message: `${tool.name} (already installed, no upgrade path on ${platform})` };
+    }
+    let beforeVersion = "";
+    try {
+      beforeVersion = execSync(`${tool.cmd} --version 2>&1 | head -1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+    } catch {}
+    try {
+      execSync(upgradeCmd, { stdio: "pipe", timeout: 120_000, encoding: "utf-8" });
+      let afterVersion = "";
+      try {
+        afterVersion = execSync(`${tool.cmd} --version 2>&1 | head -1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+      } catch {}
+      const upgraded = beforeVersion && afterVersion && beforeVersion !== afterVersion;
+      const verbInfix = upgraded ? "upgraded" : "up-to-date";
+      const versionTag = afterVersion ? ` (${afterVersion})` : "";
+      return { ok: true, message: `${tool.name} ${verbInfix}${versionTag}` };
+    } catch (err) {
+      const msg = String(err.stderr || err.message || err).split("\n")[0].slice(0, 120);
+      return { ok: true, message: `${tool.name} present (upgrade attempt failed: ${msg})` };
+    }
+  }
+
+  // ── Fresh install ──────────────────────────────────────────────────────
+  if (!installCmd) {
+    return { ok: false, message: `${tool.name} skipped — no install command for ${platform}` };
+  }
+  try {
+    execSync(installCmd, { stdio: "pipe", timeout: 240_000, encoding: "utf-8" });
+    let version = "";
+    try {
+      version = execSync(`${tool.cmd} --version 2>&1 | head -1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 }).trim().split("\n")[0];
+    } catch {}
+    return { ok: true, message: `${tool.name} installed${version ? ` (${version})` : ""}` };
+  } catch (err) {
+    const msg = String(err.stderr || err.message || err).split("\n")[0].slice(0, 120);
+    return { ok: false, message: `${tool.name} install failed (${msg})` };
+  }
+}
+
+/**
+ * Run all bootstrap tools quietly. Used at the start of `alvin-bot setup` and
+ * in `alvin-bot update`. Skipped entirely if the caller passes
+ * `--no-bootstrap-tools`. On unsupported platforms (Windows etc.) this is a
+ * silent no-op — the user can install manually.
+ */
+async function ensureBootstrapTools(opts = {}) {
+  if (opts.skip) return;
+  const platform = detectPlatformPm();
+  if (!platform) return;
+
+  console.log("\n🎬 Setting up media tools (yt-dlp + ffmpeg)...");
+
+  // macOS needs brew on PATH — same trick as ensureBrewOnPath() uses.
+  if (platform === "macos" && !hasCommand("brew")) {
+    if (!ensureBrewOnPath()) {
+      console.log("  ⚠️  Skipping media-tool bootstrap — Homebrew not installed.");
+      console.log("      To enable: install brew from https://brew.sh and re-run setup.");
+      return;
+    }
+  }
+
+  for (const tool of BOOTSTRAP_TOOLS) {
+    const result = bootstrapOneTool(tool, platform);
+    console.log(`  ${result.ok ? "✓" : "⚠"} ${result.message}`);
+  }
+  console.log("");
+}
+
 function tryNpx(args) {
   try {
     execSync(`npx --no-install ${args}`, { stdio: "pipe", timeout: 5000 });
@@ -727,6 +900,578 @@ async function validateProviderKey(providerKey, apiKey) {
   }
 }
 
+// ─── Provider config (shared between setup wizard and `provider switch`) ─────
+//
+// Encapsulates the CLI-install + auth-login flow for OAuth-style providers
+// (claude-sdk, codex-cli) and the API-key prompt+validate flow for everything
+// else. Returns a `{ ok, apiKey }` so callers can decide what to do with the
+// .env (the setup wizard writes everything at once; `provider switch` does a
+// targeted merge).
+
+const PROVIDER_KEY_MAP = {
+  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",
+};
+
+/**
+ * Find the codex CLI binary if installed. Returns the absolute path or null.
+ */
+function findCodexBinary() {
+  try {
+    const out = execSync("command -v codex", { stdio: "pipe", encoding: "utf-8" });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the claude CLI binary, checking PATH and common install paths.
+ * Returns the absolute path or null. Mirrors the search in
+ * validateProviderKey("claude-sdk", ...).
+ */
+function findClaudeBinary() {
+  try {
+    const out = execSync("command -v claude", { stdio: "pipe", encoding: "utf-8" });
+    if (out.trim()) return out.trim();
+  } catch {}
+  for (const p of [join(homedir(), ".local", "bin", "claude"), "/usr/local/bin/claude"]) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Interactive Claude SDK setup: ensures the native claude CLI is installed,
+ * runs `claude auth login` if not authenticated. Returns { ok: bool }.
+ *
+ * Designed to be called both from the setup wizard and from
+ * `alvin-bot provider switch claude-sdk`.
+ */
+async function configureClaudeSdkInline() {
+  let cliPath = findClaudeBinary();
+  if (cliPath) {
+    console.log(`  ✅ Claude CLI found at ${cliPath}`);
+  } else {
+    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 with:\n    curl -fsSL https://claude.ai/install.sh | sh`);
+    console.log(`  (npm install @anthropic-ai/claude-code is the alternative path.)\n`);
+
+    const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+    const doInstall = (await ask(`  Install now via the official installer? (y/n): `)).trim().toLowerCase();
+    if (yc.includes(doInstall)) {
+      console.log(`\n  Installing Claude CLI...`);
+      try {
+        execSync("curl -fsSL https://claude.ai/install.sh | sh", { stdio: "inherit", timeout: 120_000 });
+        const localBin = join(homedir(), ".local", "bin");
+        if (!process.env.PATH.includes(localBin)) {
+          process.env.PATH = `${localBin}:${process.env.PATH || ""}`;
+        }
+        cliPath = findClaudeBinary();
+        if (cliPath) console.log(`  ✅ Claude CLI installed at ${cliPath}\n`);
+      } catch {
+        console.log(`  ❌ Installation failed. Run manually:  curl -fsSL https://claude.ai/install.sh | sh`);
+      }
+    }
+  }
+
+  if (!cliPath) return { ok: false };
+
+  console.log(`  Checking Claude SDK authentication...`);
+  const authResult = await validateProviderKey("claude-sdk", null);
+  if (authResult.ok && !authResult.warning) {
+    console.log(`  ✅ ${authResult.detail}\n`);
+    return { ok: true };
+  }
+
+  // ok-with-warning OR not-ok — offer login.
+  if (authResult.warning) {
+    console.log(`  ⚠️  ${authResult.warning}\n`);
+  } else {
+    console.log(`  ⚠️  ${authResult.error}\n`);
+  }
+  const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+  const doLogin = (await ask(`  Run 'claude auth login' now? (Y/n): `)).trim().toLowerCase();
+  if (doLogin === "" || yc.includes(doLogin)) {
+    try {
+      execSync(`"${cliPath}" auth login --claudeai`, { stdio: "inherit", timeout: 180_000 });
+    } catch {
+      console.log(`\n  ⚠️  Auto-login failed/cancelled. Run in another terminal:  claude auth login`);
+      await ask(`  Press Enter when you've logged in (or to continue without): `);
+    }
+    const recheck = await validateProviderKey("claude-sdk", null);
+    if (recheck.ok && !recheck.warning) {
+      console.log(`\n  ✅ Claude SDK authenticated.\n`);
+      return { ok: true };
+    }
+    if (recheck.ok && recheck.warning) {
+      console.log(`\n  ⚠️  ${recheck.warning}`);
+      console.log(`     The bot will still try to use the Agent SDK at runtime.\n`);
+      return { ok: true };
+    }
+    console.log(`\n  ❌ Still not authenticated: ${recheck.error}`);
+    return { ok: false };
+  }
+  console.log(`  Skipping login. Run 'claude auth login' later to enable AI responses.`);
+  return { ok: true };  // CLI present, user explicitly skipped login — let it through
+}
+
+/**
+ * Interactive OpenAI Codex CLI setup: ensures `codex` is installed, runs
+ * `codex login` if not authenticated (ChatGPT-Plus/Pro/Max OAuth).
+ */
+async function configureCodexCliInline() {
+  let cliPath = findCodexBinary();
+  if (cliPath) {
+    console.log(`  ✅ codex CLI found at ${cliPath}`);
+  } else {
+    console.log(`  ⚠️  codex CLI not installed.`);
+    console.log(`\n  Install with one of:`);
+    console.log(`    npm install -g @openai/codex     (recommended)`);
+    console.log(`    brew install codex\n`);
+    const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+    const doInstall = (await ask(`  Install via npm now? (y/n): `)).trim().toLowerCase();
+    if (yc.includes(doInstall)) {
+      console.log(`\n  Installing @openai/codex...`);
+      try {
+        execSync("npm install -g @openai/codex", { stdio: "inherit", timeout: 120_000 });
+        cliPath = findCodexBinary();
+        if (cliPath) console.log(`  ✅ codex CLI installed at ${cliPath}\n`);
+      } catch {
+        console.log(`  ❌ Installation failed. Run manually:  npm install -g @openai/codex`);
+      }
+    }
+  }
+
+  if (!cliPath) return { ok: false };
+
+  // Check login status — `codex login status` exits 0 when logged in.
+  let loggedIn = false;
+  try {
+    const out = execSync(`"${cliPath}" login status 2>&1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 });
+    if (/Logged in/i.test(out)) loggedIn = true;
+  } catch {}
+
+  if (loggedIn) {
+    console.log(`  ✅ codex CLI is logged in.\n`);
+    return { ok: true };
+  }
+
+  console.log(`  ⚠️  codex CLI not logged in.`);
+  console.log(`     'codex login' opens a browser — sign in with your ChatGPT account.\n`);
+  const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+  const doLogin = (await ask(`  Run 'codex login' now? (Y/n): `)).trim().toLowerCase();
+  if (doLogin === "" || yc.includes(doLogin)) {
+    try {
+      execSync(`"${cliPath}" login`, { stdio: "inherit", timeout: 240_000 });
+    } catch {
+      console.log(`\n  ⚠️  codex login failed/cancelled.`);
+    }
+    try {
+      const out = execSync(`"${cliPath}" login status 2>&1`, { stdio: "pipe", encoding: "utf-8" });
+      if (/Logged in/i.test(out)) {
+        console.log(`\n  ✅ codex CLI is logged in.\n`);
+        return { ok: true };
+      }
+    } catch {}
+    console.log(`\n  ⚠️  Still not logged in — run 'codex login' later to enable.`);
+    return { ok: false };
+  }
+  console.log(`  Skipping login. Run 'codex login' later to enable AI responses.`);
+  return { ok: true };
+}
+
+/**
+ * Interactive API-key flow for providers that authenticate with a key
+ * (groq, nvidia, gemini, openai, openrouter, …). Validates the key against
+ * the provider's API where possible. Returns { ok, apiKey }.
+ */
+async function configureApiKeyInline(provider, opts = {}) {
+  const envKey = provider.envKey;
+  if (!envKey) return { ok: true, apiKey: "" };
+
+  const existing = opts.existingKey || "";
+  if (existing) {
+    console.log(`\n  Existing ${envKey} found in .env — validating first...`);
+    const test = await validateProviderKey(provider.key, existing);
+    if (test.ok) {
+      console.log(`  ✅ ${test.detail}\n`);
+      return { ok: true, apiKey: existing };
+    }
+    console.log(`  ⚠️  Existing key invalid: ${test.error}\n`);
+  }
+
+  console.log(`  Get an API key for ${provider.name}: ${provider.signup || "(see provider docs)"}\n`);
+  let apiKey = (await ask(`  ${envKey}: `)).trim();
+  if (!apiKey) {
+    console.log(`  ⚠️  No API key provided — provider won't work until configured.`);
+    return { ok: false, apiKey: "" };
+  }
+
+  console.log(`\n  Validating...`);
+  let result = await validateProviderKey(provider.key, apiKey);
+  if (result.ok) {
+    console.log(`  ✅ ${result.detail}\n`);
+    return { ok: true, apiKey };
+  }
+  console.log(`  ❌ ${result.error}\n`);
+
+  const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+  const retry = (await ask(`  Try a different key? (y/n): `)).trim().toLowerCase();
+  if (yc.includes(retry)) {
+    apiKey = (await ask(`  ${envKey}: `)).trim();
+    if (apiKey) {
+      result = await validateProviderKey(provider.key, apiKey);
+      if (result.ok) {
+        console.log(`  ✅ ${result.detail}\n`);
+        return { ok: true, apiKey };
+      }
+      console.log(`  ❌ ${result.error}`);
+    }
+  }
+  console.log(`  ⚠️  Saving the key anyway — fix later in ~/.alvin-bot/.env if it's wrong.`);
+  return { ok: !!apiKey, apiKey };
+}
+
+// ─── .env merge helpers ──────────────────────────────────────────────────────
+//
+// `provider switch` mutates ~/.alvin-bot/.env by touching exactly two lines:
+// PRIMARY_PROVIDER and the new provider's API-key entry. Everything else
+// (BOT_TOKEN, ALLOWED_USERS, FALLBACK_PROVIDERS, WEB_*, comments, blank
+// lines, custom additions) is preserved byte-for-byte. The OLD provider's
+// API key is commented out — never deleted — so the user can roll back
+// without re-pasting secrets they may not have anywhere else.
+
+/**
+ * Set (or append) `KEY=value` in .env content. If a matching commented line
+ * (`# KEY=...`) exists, it's replaced with the active form. Otherwise the
+ * new line is appended at the end with a leading blank line if needed.
+ */
+function setEnvKey(content, key, value) {
+  const lines = content.split("\n");
+  const activeRe = new RegExp(`^${key}\\s*=`);
+  const commentedRe = new RegExp(`^#\\s*${key}\\s*=`);
+  for (let i = 0; i < lines.length; i++) {
+    if (activeRe.test(lines[i]) || commentedRe.test(lines[i])) {
+      lines[i] = `${key}=${value}`;
+      return lines.join("\n");
+    }
+  }
+  // Append. Ensure there's a separating blank line.
+  if (lines.length && lines[lines.length - 1].trim() !== "") lines.push("");
+  lines.push(`${key}=${value}`);
+  return lines.join("\n");
+}
+
+/**
+ * Comment out an active `KEY=...` line with a note. Leaves already-commented
+ * lines alone, leaves the line absent if it wasn't there. Returns the new
+ * content + a `changed` flag for caller logging.
+ */
+function commentEnvKey(content, key, note) {
+  const lines = content.split("\n");
+  const activeRe = new RegExp(`^${key}\\s*=`);
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (activeRe.test(lines[i])) {
+      const today = new Date().toISOString().slice(0, 10);
+      const stamp = note ? `  # parked ${today}: ${note}` : `  # parked ${today}`;
+      lines[i] = `# ${lines[i]}${stamp}`;
+      changed = true;
+      break;
+    }
+  }
+  return { content: lines.join("\n"), changed };
+}
+
+/**
+ * Read PRIMARY_PROVIDER from .env content (handles "...=value" with optional
+ * quotes/whitespace). Returns the key or null if not set.
+ */
+function readPrimaryProvider(content) {
+  const m = content.match(/^PRIMARY_PROVIDER\s*=\s*"?([^"#\s]+)"?\s*$/m);
+  return m ? m[1] : null;
+}
+
+/**
+ * Read an arbitrary key from .env content. Returns the value or null.
+ */
+function readEnvValue(content, key) {
+  const re = new RegExp(`^${key}\\s*=\\s*"?([^"#\\n]+?)"?\\s*(?:#.*)?$`, "m");
+  const m = content.match(re);
+  return m ? m[1].trim() : null;
+}
+
+// ─── `alvin-bot provider` subcommands ────────────────────────────────────────
+
+/**
+ * Resolve a provider key (or aliases) to a PROVIDERS entry. Returns null if
+ * unknown. Lets users use "claude" → "claude-sdk", "codex" → "codex-cli",
+ * "nvidia" → "nvidia-kimi-k2.5", "gemini" → "gemini-2.5-flash" — so they
+ * don't have to remember the exact slug.
+ */
+function resolveProviderKey(input) {
+  const lower = input.trim().toLowerCase();
+  const aliases = {
+    "claude": "claude-sdk",
+    "claudesdk": "claude-sdk",
+    "codex": "codex-cli",
+    "nvidia": "nvidia-kimi-k2.5",
+    "nim": "nvidia-kimi-k2.5",
+    "kimi": "nvidia-kimi-k2.5",
+    "gemini": "gemini-2.5-flash",
+    "google": "gemini-2.5-flash",
+    "gpt": "openai",
+    "gpt4": "openai",
+    "gpt4o": "openai",
+    "offline": "offline-gemma4",
+    "gemma": "offline-gemma4",
+    "gemma4": "offline-gemma4",
+  };
+  const resolved = aliases[lower] || lower;
+  // Codex-cli isn't in PROVIDERS but is supported by switch/list.
+  if (resolved === "codex-cli") {
+    return {
+      key: "codex-cli",
+      name: "OpenAI Codex CLI (ChatGPT OAuth)",
+      desc: () => "Use your ChatGPT Plus/Pro/Max subscription via the codex CLI. OAuth login, no API key needed.",
+      free: false,
+      envKey: null,
+      signup: "https://chat.openai.com",
+      model: "gpt-5",
+      needsCLI: false,
+      needsCodexCLI: true,
+    };
+  }
+  return PROVIDERS.find(p => p.key === resolved) || null;
+}
+
+/**
+ * Compute installed / authenticated / has-key status for a provider, given
+ * the current .env content. Returns a short status string with an icon.
+ */
+function providerStatus(provider, envContent) {
+  if (provider.offline) {
+    return hasOllama() ? "✓ Ollama installed" : "· Ollama not installed";
+  }
+  if (provider.needsCLI) {
+    return findClaudeBinary() ? "✓ Claude CLI installed" : "· Claude CLI not installed";
+  }
+  if (provider.needsCodexCLI) {
+    return findCodexBinary() ? "✓ codex CLI installed" : "· codex CLI not installed";
+  }
+  if (provider.envKey) {
+    const v = readEnvValue(envContent, provider.envKey);
+    return v ? `✓ ${provider.envKey} set` : `· ${provider.envKey} not set`;
+  }
+  return "—";
+}
+
+function envPath() {
+  return join(DATA_DIR, ".env");
+}
+
+function loadEnvOrExit(silent = false) {
+  const p = envPath();
+  if (!existsSync(p)) {
+    if (!silent) {
+      console.log(`\n❌ No .env at ${p}`);
+      console.log(`   Run 'alvin-bot setup' first to configure the bot.\n`);
+    }
+    return null;
+  }
+  return { path: p, content: readFileSync(p, "utf-8") };
+}
+
+async function providerList() {
+  const loaded = loadEnvOrExit(true);
+  const env = loaded?.content || "";
+  const current = readPrimaryProvider(env);
+
+  console.log(`\n📋 AI providers — current: ${current ? `🟢 ${current}` : "(not configured)"}\n`);
+
+  // Build a uniform list: wizard PROVIDERS + codex-cli alias.
+  const ALL = [...PROVIDERS, resolveProviderKey("codex-cli")];
+  for (const p of ALL) {
+    const marker = p.key === current ? "→" : " ";
+    const badge = p.offline ? "🔒" : p.free ? "🆓" : "💰";
+    const status = providerStatus(p, env);
+    console.log(`  ${marker} ${badge} ${p.key.padEnd(22)}  ${status}`);
+    console.log(`       ${p.name}`);
+  }
+  console.log(`\n  Switch with:  alvin-bot provider switch <key>`);
+  console.log(`  Aliases: claude, codex, gemini, nvidia, gpt, gemma\n`);
+}
+
+async function providerShow() {
+  const loaded = loadEnvOrExit();
+  if (!loaded) return;
+  const current = readPrimaryProvider(loaded.content);
+  if (!current) {
+    console.log(`\n⚠️  PRIMARY_PROVIDER not set in .env.\n`);
+    return;
+  }
+  const provider = resolveProviderKey(current);
+  if (!provider) {
+    console.log(`\n⚠️  PRIMARY_PROVIDER='${current}' but no matching provider definition found.\n`);
+    return;
+  }
+  console.log(`\n📍 Current AI provider\n`);
+  console.log(`  Key:     ${provider.key}`);
+  console.log(`  Name:    ${provider.name}`);
+  console.log(`  Model:   ${provider.model || "(default)"}`);
+  console.log(`  Status:  ${providerStatus(provider, loaded.content)}`);
+  if (provider.envKey) {
+    const v = readEnvValue(loaded.content, provider.envKey);
+    console.log(`  Key var: ${provider.envKey}${v ? " (set)" : " (missing!)"}`);
+  }
+  console.log(``);
+  const fb = readEnvValue(loaded.content, "FALLBACK_PROVIDERS");
+  if (fb) console.log(`  Fallbacks: ${fb}\n`);
+  console.log(`  Doctor:  alvin-bot provider doctor`);
+  console.log(`  Switch:  alvin-bot provider switch <key>\n`);
+}
+
+/**
+ * Switch the bot to a different AI provider. Runs the same interactive
+ * configuration as the setup wizard (CLI install + auth login or API-key
+ * prompt) but only touches the provider-related lines in .env. The previous
+ * provider's API key is commented out (never deleted) so rollback is trivial.
+ */
+async function providerSwitch(targetKey) {
+  if (!targetKey) {
+    console.log(`Usage: alvin-bot provider switch <key>`);
+    console.log(`Available keys: see 'alvin-bot provider list'`);
+    return;
+  }
+  const target = resolveProviderKey(targetKey);
+  if (!target) {
+    console.log(`\n❌ Unknown provider: '${targetKey}'`);
+    console.log(`   See 'alvin-bot provider list' for valid keys.\n`);
+    return;
+  }
+  const loaded = loadEnvOrExit();
+  if (!loaded) return;
+
+  let content = loaded.content;
+  const fromKey = readPrimaryProvider(content);
+  const fromProvider = fromKey ? resolveProviderKey(fromKey) : null;
+
+  console.log(`\n🔁 Switching AI provider`);
+  console.log(`   from:  ${fromKey || "(not set)"}${fromProvider ? `  (${fromProvider.name})` : ""}`);
+  console.log(`   to:    ${target.key}  (${target.name})\n`);
+
+  if (fromKey === target.key) {
+    console.log(`  ℹ️  Already on ${target.key}. Nothing to do.\n`);
+    return;
+  }
+
+  // ── Run provider-specific configuration ────────────────────────────────
+  let newKey = "";
+  if (target.offline) {
+    const ok = await setupOfflineGemma4();
+    if (!ok) {
+      console.log(`  ❌ Offline setup didn't complete — keeping current provider.\n`);
+      return;
+    }
+  } else if (target.needsCLI) {
+    const res = await configureClaudeSdkInline();
+    if (!res.ok) {
+      console.log(`  ❌ Claude SDK setup didn't complete — keeping current provider.\n`);
+      return;
+    }
+  } else if (target.needsCodexCLI) {
+    const res = await configureCodexCliInline();
+    if (!res.ok) {
+      console.log(`  ❌ Codex CLI setup didn't complete — keeping current provider.\n`);
+      return;
+    }
+  } else if (target.envKey) {
+    const existingKey = readEnvValue(content, target.envKey) || "";
+    const res = await configureApiKeyInline(target, { existingKey });
+    if (!res.ok) {
+      console.log(`  ❌ No usable API key — keeping current provider.\n`);
+      return;
+    }
+    newKey = res.apiKey;
+  }
+
+  // ── Merge-update .env ──────────────────────────────────────────────────
+  content = setEnvKey(content, "PRIMARY_PROVIDER", target.offline ? "ollama" : target.key);
+  if (target.envKey && newKey) {
+    content = setEnvKey(content, target.envKey, newKey);
+  }
+  // Park the previous provider's API key (if it had one and the new
+  // provider uses a *different* key). Same-key reuse (e.g. switching
+  // between OpenAI and gpt-4o which both use OPENAI_API_KEY) is left alone.
+  if (fromProvider && fromProvider.envKey && fromProvider.envKey !== target.envKey) {
+    const parked = commentEnvKey(content, fromProvider.envKey, `was for ${fromProvider.key}, kept for rollback`);
+    if (parked.changed) {
+      console.log(`  📦 Parked old ${fromProvider.envKey} (commented out, not deleted).`);
+    }
+    content = parked.content;
+  }
+
+  writeFileSync(loaded.path, content, { mode: 0o600 });
+  console.log(`\n  ✅ ${loaded.path} updated.`);
+
+  // ── Offer restart under launchd ─────────────────────────────────────────
+  if (process.platform === "darwin") {
+    const { plistPath, label } = launchdPaths();
+    if (existsSync(plistPath)) {
+      const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+      const doRestart = (await ask(`  Restart the launchd-managed bot to apply? (Y/n): `)).trim().toLowerCase();
+      if (doRestart === "" || yc.includes(doRestart)) {
+        try {
+          execSync(`launchctl kickstart -k gui/$UID/${label}`, { stdio: "inherit" });
+          console.log(`  ✅ Bot restarted.`);
+        } catch (err) {
+          console.log(`  ⚠️  Restart failed — run manually: launchctl kickstart -k gui/$(id -u)/${label}`);
+        }
+      } else {
+        console.log(`  ℹ️  Restart later with: launchctl kickstart -k gui/$(id -u)/${label}`);
+      }
+    } else {
+      console.log(`  ℹ️  Restart the bot to apply (whatever your process manager is).`);
+    }
+  }
+  console.log(``);
+}
+
+async function providerDoctor() {
+  const loaded = loadEnvOrExit();
+  if (!loaded) return;
+  const current = readPrimaryProvider(loaded.content);
+  if (!current) {
+    console.log(`\n⚠️  PRIMARY_PROVIDER not set.\n`);
+    return;
+  }
+  const provider = resolveProviderKey(current);
+  console.log(`\n🩺 Provider health: ${current}\n`);
+  if (!provider) {
+    console.log(`  ❌ No definition for '${current}' in PROVIDERS.\n`);
+    return;
+  }
+  const key = provider.envKey ? readEnvValue(loaded.content, provider.envKey) : null;
+  const result = await validateProviderKey(provider.key, key);
+  if (result.ok && result.warning) {
+    console.log(`  ⚠️  ${result.warning}`);
+    console.log(`     ${result.detail}\n`);
+  } else if (result.ok) {
+    console.log(`  ✅ ${result.detail}\n`);
+  } else {
+    console.log(`  ❌ ${result.error}\n`);
+    console.log(`  Fix:  alvin-bot provider switch ${provider.key}`);
+    console.log(`        (or:  alvin-bot provider switch <other>)\n`);
+  }
+}
+
 /**
  * Validate a Telegram bot token by calling getMe.
  * Returns { ok: true, botName: "@username" } or { ok: false, error: "reason" }.
@@ -819,7 +1564,7 @@ async function runPostSetupValidation(providerKey, apiKey, botToken, webPort) {
  */
 function parseSetupArgs(argv) {
   const args = {};
-  const flags = new Set(["--non-interactive", "-y", "--yes", "--skip-validation"]);
+  const flags = new Set(["--non-interactive", "-y", "--yes", "--skip-validation", "--no-bootstrap-tools"]);
   const valueFlags = [
     "--bot-token", "--allowed-users", "--primary-provider",
     "--groq-key", "--google-key", "--openai-key", "--nvidia-key",
@@ -972,6 +1717,11 @@ async function setup() {
     return;
   }
 
+  // ── Auto-bootstrap media tools (yt-dlp + ffmpeg) ───────────────────────
+  // Runs before any prompts so the user doesn't have to wait at the end.
+  // Single-line status per tool. Failure is non-fatal — setup continues.
+  await ensureBootstrapTools({ skip: !!args["no-bootstrap-tools"] });
+
   // ── Step 1: Telegram Bot
   console.log(`\n━━━ ${t("setup.step1")} ━━━`);
   console.log(t("setup.step1.intro"));
@@ -1774,6 +2524,8 @@ async function doctor() {
 async function update() {
   console.log(`${t("update.title")}\n`);
 
+  const skipBootstrap = process.argv.includes("--no-bootstrap-tools");
+
   try {
     const isGit = existsSync(resolve(process.cwd(), ".git"));
 
@@ -1790,6 +2542,10 @@ async function update() {
       execSync("npm update alvin-bot", { stdio: "inherit" });
       console.log(`\n  ✅ ${t("update.done")}`);
     }
+
+    // Refresh bootstrap media tools (yt-dlp / ffmpeg) — keeps them in sync
+    // with the alvin-bot version that just got installed.
+    await ensureBootstrapTools({ skip: skipBootstrap });
   } catch (err) {
     console.error(`\n  ❌ ${t("update.failed")} ${err.message}`);
   }
@@ -2179,6 +2935,34 @@ switch (cmd) {
     }
     break;
   }
+  case "provider": {
+    const sub = (process.argv[3] || "list").toLowerCase();
+    const arg = process.argv[4];
+    const done = (p) => p.then(() => closeRL()).catch(err => { console.error(err); closeRL(); });
+    if (sub === "list" || sub === "ls") {
+      done(providerList());
+    } else if (sub === "show" || sub === "current") {
+      done(providerShow());
+    } else if (sub === "switch" || sub === "use" || sub === "set") {
+      done(providerSwitch(arg));
+    } else if (sub === "doctor" || sub === "check" || sub === "validate") {
+      done(providerDoctor());
+    } else {
+      console.log("Usage: alvin-bot provider <list|show|switch <key>|doctor>");
+      console.log("");
+      console.log("  list                    — Show all providers + current selection + per-provider status");
+      console.log("  show                    — Detailed info on the currently configured provider");
+      console.log("  switch <key>            — Switch to a different provider (interactive setup + .env merge)");
+      console.log("  doctor                  — Validate the current provider's auth/key against its API");
+      console.log("");
+      console.log("Aliases accepted for <key>: claude, codex, gemini, nvidia, gpt, gemma");
+      console.log("Examples:");
+      console.log("  alvin-bot provider switch groq");
+      console.log("  alvin-bot provider switch claude-sdk");
+      console.log("  alvin-bot provider switch codex");
+    }
+    break;
+  }
   case "update":
     update().catch(console.error);
     break;
@@ -2542,6 +3326,7 @@ ${t("cli.commands")}
   audit     Security health check (permissions, secrets, config)
   search    Search your assets, memories, and skills
   tools     List / install optional capability tools (ffmpeg, pandoc, …)
+  provider  List / switch AI provider (claude, codex, groq, gemini, …)
   browser   Manage bot-owned Chromium (start/stop/goto/shot/doctor)
   update    ${t("cli.updateDesc")}
   start     ${t("cli.startDesc")} (background via PM2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.23.1",
+  "version": "4.25.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",